Digiteal Reference documentation

Welcome to the Digiteal technical reference documentation.

Digiteal allows you to create e-invoices and handle payments. This document will provide a high level overview on how to use these services. Links to the more technical description of the API's are present per high level overview allowing you to learn our system through a top-down approach. The documentation is split in 2 major parts:

  • e-invoices
  • payments
Do you need technical support?
contact support
Do you have a sales question?
contact sales

Who

This document is provided for:

Companies that want to integrate with the Digiteal services in order to send out their bills to their Digiteal clients. These companies use a custom software solution to send out their bills.

Integrators, software companies, ERP, that are willing to provide a plugin for their clients to allow them sending out bills through Digiteal, avoiding hazardous customization.

If you have any questions, remarks or propositions please contact support

What

This document will guide you through the technical specifications enabling you to:

  • issue invoices that will contain the Scan2Pay QR code and for those invoices to be visible in the Digiteal web portal and mobile application.
  • upload a invoice document which is linked to a previously generated invoice.
  • integrate a payment button in your application

Naming conventions

  • Issuer : the company that is emitting the invoice.
  • Requester : the company which is requesting a payment.
  • Integrator: the company acting as an integrator for other companies who want to request a payment.

Technology

All services provided by digiteal are exposed as REST services and use JSON as interchange format.

All services implemented by the requester should be exposed as REST services and use JSON as interchange format.

All services will be provided over a secure HTTP connection.

Authentication

The service is using a secure HTTP connection combined with basic authentication mechanism for authentication. The login and password are the same as chosen by you during the registration. For more information on the registration process please consult the registration documentation

Strong authentication solutions such as 2-way SSL are also supported. Contact technical support to register your public certificate if this is your prefered authentication method.

Registration process

If you want to make use of the Digiteal services you need to register your free account on the Digiteal platform. With this account you will be able to generate invoices and upload invoice documents. The clients that chose to use the Digiteal platform to receive your bills will be notified, have the possibility to view the invoices and pay them.

If you want to integrate our payment solution in your application please contact our sales for anything related to conditions and dev support for anything related the technical integration of our solution.

Registration form

In order to create invoices you need to register an account on the DigiTeal platform. This can be done on the registration page

During this phase we need the following information

  • Company name: as known by the Crossroads Bank for Enterprises
  • VAT number
  • E-mail

Confirm email

As soon as you hit the “Sign up” button, Digiteal will send an email to the email address you provided. This allows us to verify if this address is correct and related to you. Click on the confirmation link to complete this process.

This e-mail address will act as login for the Digiteal platform and the web services.

On your right you see a screenshot with the confirmation after submitting the registration and the confirmation mail.

Complete profile

Once the validation step is completed, your profile has to be completed with the following information:

  • provide one or more valid bank account(s)
  • provide a copy of the documents (PDF format) to prove that you are the responsible for your company
    • copy of the identity card
    • copy of the statutes of your company

Done

Once these steps are completed the Digiteal Team will validate your profile details. You will be notified by email once your account has been activated or be provided with the reasons why it can’t be activated. When your account is validated by the Digiteal team you will be able to send invoice metadata, upload the matching original documents and generate invoices.

Prefilled registration

To simplify the on-boarding of your customers you can send them a link with some prefilled information. They will be redirected to our web platform and should only choose a password to finish the first step of the registration.

Company

digiteal-env

the environment on which you want to use this (https://app.digiteal.eu, https://test.digiteal.eu)

This value is passed as a PATH parameter. Do not forget the /? after this value. If this is not present then the form will not be pre-filled

e-mail

the email address of your client

vatNumber

the vat number of your customer enterprise

ID

your integrator ID (can be find in your profile)

name

the name of your client's company

{digiteal-env}/#/register/{e-mail}/?vatNumber={vatNumber}&integratorID= {ID}&companyName={name}&forBusiness=true

E-invoices overview

On your right you see a schematical overview of the process for creating and paying an e-invoice using Digiteal. In this overview the focus is mainly on the creation. The payment is discussed more indepth in the handling a Payment section. Here it is mentioned as a single step in the process.

The whole flow is started when your system prepares the invoice for a specific customer. It has to call the Digiteal platform providing the necessary invoice data and customer information. These informations are stored and a payment image is generated. The images include the QR code following the guidelines of the EPC. More information about the EPC standard here : European Payment Councils

The output of the service will contain a payment image, the identifier of the invoice in Digiteal and the preferred delivery method of the client. If the client is already known and he/she prefers to receive his/her invoices in the Digiteal platform then a notification will be sent.

If the client has indicated he uses the Digiteal platform to receive his mails you can upload your custom invoice document. This document will be stored and kept for 10 years. The client will be able to consult this document at anytime and on multiple supported platforms (web, mobile).

If the client is unknown or hasn't indicated his preference you should use your other distribution modes to send the invoice containing the QR.

When the client receives the push notification he can consult the invoice details and proceed to the payment using the one-click pay. More information on payments through the Digiteal platform please consult the Payment section

Each invoice generation is logged to detect malpractice and prevent DOS attacks.

API invoice details provides an overview of the provided services and gives a detailed description of the input and output parameters.

Create/Update invoice.

In order to create an invoice, Digiteal needs to receive information about

A invoice can have 2 statuses :

  • DRAFT
  • PUBLISHED
When not specified the default value is PUBLISHED which allows no updates.

The platform provides the possibility to introduce an invoice with a DRAFT status which can be updated later on. Users will not be notified for these invoices.

Issuer

When calling the service, the authentication parameters (username and password) have to be provided (HTTP Basic authentication mechanism). You do not have to specify any identifier related to your company in the input parameters. Based on the authentication parameters the Digiteal platform knows the company that sent the request.

In case of 2-way ssl authentification, the identification will be done using the public certificate sent during the ssl handshake.

For more information on how to register on the Digiteal platform please consult the Registration section. Upon registration, you will be authenticated by default using the username and password you chose.

If you prefer using SSL 2-way authentication please contact technical support

Bank Account

A bank account is identified by its IBAN code. (BIC is not a required field)

Important: The platform allows a company to define multiple bank accounts. Whenever a company has more than one confirmed bank accounts and no default is set in Digiteal), this parameter becomes mandatory. Otherwise our platform will not know on which bank account this invoice is supposed to be paid.
Defining a default bank account in Digiteal

Log on to the application, go to 'my profile' and select the bank account tab.

If multiple bank accounts are registered then you are able to switch or define a default one by clicking on the “set as default button”. If there is only 1 bank account defined, it will be considered as the default one.

Customer

The invoice will be linked to a customer. A customer can be identified by:

  • The internal identifier in your system
  • His email address

Important:
Providing customer information can be done by 3 different ways:

  • no internal client id or email address is provided:
    no information about the customer will be stored. Only the generated invoice will be kept (for billing & statistic purposes). Your end client will not be able to access the invoice on the Digiteal platform.
  • an internal client id is provided:
    If the internal client id is provided a customer will be stored in our system. Every new invoice request generated with this client id included will be linked. The end user will not be able to access the invoice on the Digiteal platform yet. In that case, Digiteal cannot be used to present the invoice yet. If the issuer calls the service later on using the same client id AND the email address the link will be created between the client id and email address thus allowing the end user to access his invoice.
  • an internal client id and email address are provided:
    Providing the internal client id and the email address allows our system to notify the end user. The end user will be able to consult the invoice in Digiteal.

Other

For a more detailed view on the input parameters of the invoice creation requests please have a look at the API details

Our system allows you to add your own internal identifier to the invoice. Later on, you can use your own internal identifier to link documents to the generated invoice.

The amount is a required field. The only case where the amount is not mandatory is when generating a payment QR using the QR generator service. Generating a QR code without the amount allows people to fill in what they want to donate and still make use of the Scan2Pay method to prefill the other fields of the payment.

Error-codes

200 OK

the invoice is created. The response will contain the image in the body. The uuid, deliveryMethod and debtorId are present in the headers.

400

BANK_ACCOUNT_NOT_FOUND :
provided information does not match any of your bank accounts in our system.

400

BANK_ACCOUNT_NOT_PROVIDED :
typically when you forget to send us the BIC and IBAN and have more than one account. The system does not know the one that should be used.

400

CUSTOMER_INFORMATION_MISSING :
mandatory fields are missing. The mandatory field are indicated: ex: Missing fields for the customer creation. [customerInternalId]

400

INVOICE_INFORMATION_MISSING :
mandatory fields for the invoice request are missing.

400

INVOICE_PUBLISHED :
Invoices that are flagged as PUBLISHED cannot be updated.

400

CONTENT_MISSING :
There was no input present in the request.

400

INVALID_FORMAT :
The specified format is incorrect

400

INVALID_PURPOSE :
The purpose is not ISO compliant

401

UNAUTHORIZED_ACCES :
there were no or incorrect credentials provided

403

ISSUER_CANNOT_EMIT :
is thrown when your profile is not yet activated or invalid.

415

UNSUPPORTED_MEDIA :
The service is called using an unsupported media type. Only JSON is supported when performing a POST.

500

GENERAL :
An internal server error occured. Contact support with information concerning your error (date, time, issuer) to know more about this particular issue.

Invoice Documents

This service is used to attach a PDF document to an invoice. For example, this document can be a bill but it can also be some energy usage summary or the details of a telephone bill.

Multiple documents can be attached to one invoice. A document cannot be sent if it is not related to an existing invoice. Only the emitter of a invoice can attach documents to it.

There are two services to send a document. The first one uses the UUID of the invoice as returned when the invoice was sent and the second one relies on the issuer's internal identifier.

Error codes

200 OK

An empty body response is sent. Additional headers are present (uuid of the document that you uploaded).

400

BAD_REQUEST:
Some input field is missing or wrong values were provided.

401

UNAUTHORIZED_ACCES:
there were no or incorrect credentials provided

415

UNSUPPORTED_MEDIA:
The uploaded document has an unsupported media type. The service only accepts PDF files.

Payments Introduction

The Digiteal platform not only allows the end user (your clients) to pay their invoices, it also allows you to integrate the interactive payment solution with your proprietary software. Our platform provides 2 parts necessary to create and complete an interactive payment flow.

  • a service to create a payment request hosted and implemented by Digiteal
  • an api interface to receive payment notifications hosted and implemented by you

Besides the interactive payment (user input necessary to finalize the payment) our platform allows the end users to configure automatic payments (payments executed automatically upon receiving an invoice). In this documentation, this functionality is described as the autopayment service.

Interactive Payments

This service will be called by the Digiteal platform to notify the requester that we received a confirmation to execute a payment request. The unique payment id generated during the payment request creation will be provided as input. This allows the requester’s system to link the corresponding payment request on his side. If the service of the requester is unreachable the digiteal platform will retry later on.

Payment notifications

Every day the Digiteal platform will handle the received bank transactions and notify the involved requester in push mode. If the system of the requester is not available the Digiteal platform will retry later on.

There are 4 notification types:

  • SUCCESS: payment has been confirmed
  • ERROR: an error occurred during the withdrawal.
  • REIMBURSMENT_TO_CLIENT: a reimbursement has been requested by the client. The Digiteal platform will withdraw the amount from the requester’s account.
  • REIMBURSMENT_FROM_DIGITEAL: The Digiteal platform received money from a requester for a specific client. This money will be reimbursed to the requester since our platform does not handle transfer of funds for reimbursements.

Payment Requester API provides an overview of the services that you need to implement in order to support interactive payments. This documentation contains a detailed descriptions of the input and output parameters.

Pay Button

Pay Button intro

The main goal of the pay button is to provide an easy to integrate payment solutions that allows your users to pay by simply clicking on the button. The user will be redirected to a page on which he can choose how to pay. Using the digiteal platform (using his digiteal account) or scan a QR using the digiteal mobile app.

You can use this solution by simply adding some basic html to your email template or web platform. It's important for us to keep the intregration easy, fast, robust and most certainly secure.

The pay button itself is context aware which means that the appereance will change if the payment is already executed. If you send your client an email containing the pay button and the client finalises the payment by clicking on the pay button, the next time he opens the mail the pay button will indicated that the payment has been fullfilled.

We also provide you the possibility to define your own webhook that will be called whenever the payment has been validated by the client.

Pay button (still to pay)
Pay button (payment executed)

Pay button generation

GET /api/v1/payment-request/pay-button

The response of the url can be 4 different images

  • Payment has not been paid :
  • Payment has been paid :
  • Payment execution is scheduled for a certain date :
  • The platform is unavailable :a message will be shown explaining that the payment is currently unavailable

requesterID or requesterVAT

requesterID = the identifier key of your account. This information can be found on your profile page
requesterVAT = the vatNumber of your company for which you want to initiate a payment. 1 of these 2 is required!

invoiceUUID

It is possible to link a payment button to an invoice. If you use this parameter it's no longer required to provide the amount and the creditorReference or remittanceInfo

iban

The iban where our system will transfer the money to. If none is specified the default one specified on your profile page will be used. Our system performs a validation to see if the iban is linked to your account.

amountInCents

The amount of the payment expressed in cents without comma. (only required if invoiceUUID is not used)

language

Defines the language in which the button has to be generated

creditorReference

the creditorReference of the payment (either this one or the remittanceInfo is required!) (only required if invoiceUUID is not used)

remittanceInfo

the remittanceInfo of the payment (either this one or the remittanceInfo is required!) (only required if invoiceUUID is not used)

Pay button Example

<img src="https://app.digiteal.eu/api/v1/payment-request/pay-button?requesterID=09804982031&amountInCents=1299&iban=BE987876765&language=en&creditorReference=RF654984654654>
              

Pay button execution

GET /api/v1/payment-request/pay-button/execute

The url that has to be called to execute the payment. The result can have 3 different outcomes:

  • Payment has not yet been paid : the user is presented with a choice page. Either using the digiteal platform or scanning the qr using the Digiteal app
  • The payment has alread been paid : a page with reduced information will be shown to indicate the payment is already executed
  • Unavailable page : something went wrong during the processing and an unavailability page is shown.

requesterID or requesterVAT

requesterID = the identifier key of your account. This information can be found on your profile page
requesterVAT = the vatNumber of your company for which you want to initiate a payment. 1 of these 2 is required!

invoiceUUID

It is possible to link a payment button to an invoice. If you use this parameter it's no longer required to provide the amount and the creditorReference or remittanceInfo

iban

The iban where our system will transfer the money to. If none is specified the default one specified on your profile page will be used. Our system performs a validation to see if the iban is linked to your account.

amountInCents

The amount of the payment expressed in cents without comma.

language

Defines the language in which the button has to be generated

creditorReference

the creditorReference of the payment (either this one or the remittanceInfo is required!)(only required if invoiceUUID is not used)

remittanceInfo

the remittanceInfo of the payment (either this one or the remittanceInfo is required!)(only required if invoiceUUID is not used)

Pay button Example

          <a href="https://int.digiteal.eu/api/v1/payment-request/pay-button/execute?requesterID=09804982031&amountInCents=1299&iban=BE987876765&language=en&creditorReference=RF654984654654" style="outline: none;">
            <img src="https://int.digiteal.eu/api/v1/payment-request/pay-button">
            </a>
              
Payment choice screen

Automatic payments

AutoPay setup

The Digiteal Platform allows a user to setup an auto payment configuration for his payment requests for a specific requester. By creating an auto payment configuration, the user allows the requester to automatically launch the payment request on the Digiteal platform.

AutoPay request

As a requestor, you can submit a payment request to the AutoPay service to get paid automatically (with no mandatory user intervention).

400

INCORRECT_CONTENT:
only correct json is supported

400

MISSING_INPUT_FIELDS:
The 'name of the missing field' is provided in the error message.

400

UNSUPPORTED_REQUEST_METHOD:
This service only accepts POST.

401

UNAUTHORIZED_ACCES:
There were no or incorrect credentials provided.

415

UNSUPPORTED_MEDIA:
POST only consumes application/json

415

FORBIDDEN:
Not allowed to perform this action.

Payment API details

Payment API details provides an overview of the provided services and gives a detailed description of the input and output parameters.

Payment Requester API provides an overview of the services that you need to implement in order to support interactive payments. This documentation contains a detailed descriptions of the input and output parameters.