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:
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
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
- 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.
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.
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.
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.
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
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.
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
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.
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.
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
the email address of your client
the vat number of your customer enterprise
your integrator ID (can be find in your profile)
the name of your client's company
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.
In order to create an invoice, Digiteal needs to receive information about
A invoice can have 2 statuses :
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.
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
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.
The invoice will be linked to a customer. A customer can be identified by:
- The internal identifier in your system
- His email address
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.
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.
the invoice is created. The response will contain the image in the body. The uuid, deliveryMethod and debtorId are present in the headers.
provided information does not match any of your bank accounts in our system.
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.
mandatory fields are missing. The mandatory field are indicated: ex: Missing fields for the customer creation. [customerInternalId]
mandatory fields for the invoice request are missing.
Invoices that are flagged as PUBLISHED cannot be updated.
There was no input present in the request.
The specified format is incorrect
The purpose is not ISO compliant
there were no or incorrect credentials provided
is thrown when your profile is not yet activated or invalid.
The service is called using an unsupported media type. Only JSON is supported when performing a POST.
An internal server error occured. Contact support with information concerning your error (date, time, issuer) to know more about this particular issue.
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.
An empty body response is sent. Additional headers are present (uuid of the document that you uploaded).
Some input field is missing or wrong values were provided.
there were no or incorrect credentials provided
The uploaded document has an unsupported media type. The service only accepts PDF files.
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.
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.
When something happens, the Digiteal platform will notify the requester and/or integrator through webhooks. This means that Digiteal will call your service with a well defined JSON payload. You will be able to do whatever you need with this message.
If the system of the requester/integrator is not available or responded with something else than a HTTP_OK, the Digiteal platform will retry later every hour until the message is successfully processed. If your system is failing too long or too often, we will inform you. If it continues to misbehave and with one week prior notice, we could remove your webhook.
To register webhooks you can either have a single service that receives all the notifications or you could register a specific webhook per notification type. It's up to you. Please get in touch with the Digiteal support team to arrange this with us.
As a requestor, you will received the notifications for the webhooks you registered too and that concern your company. As an integrator, you will receive the notification for all the companies that defined you as integrator.
Payment webhooks will send you TransferOfFundsNotification as JSON payload.
Here are the payment notification types:
- INITIATED: payment has been initiated by the debtor
- WITHDRAWAL_ERROR: money could not be withdrawn from the account of the debtor
- WITHDRAWAL_SUCCESS: money has been withdrawn from the account of the debtor
- REIMBURSMENT_FROM_DIGITEAL: a reimbursement has been requested by the client. The money was still in transit and it has not been transferred to the creditor yet. The Digiteal platform reimbursed the client.
- TRANSFERRED: money has been transferred to the creditor
- REIMBURSMENT_FROM_REQUESTOR: a reimbursement has been requested by the debtor. The money has already been transferred to the creditor. The Digiteal platform will withdraw the amount from the creditor’s account.
As a requestor, you can submit a payment request to the AutoPay service to get paid automatically (with no mandatory user intervention).
only correct json is supported
The 'name of the missing field' is provided in the error message.
This service only accepts POST.
There were no or incorrect credentials provided.
POST only consumes application/json
Not allowed to perform this action.
AutoPay configuration change notification
As soon as an auto-payment configuration changed, the Digiteal platform will notify the requester and/or integrator through webhooks. For the autopay configuration changes, an AutoPayConfiguration will be sent in a JSON payload.
Here are the AutoPayConfiguration notification types:
- CREATE: The autopay configuration has been created and it is active.
- UPDATE: The autopay configuration has been updated.
- SUSPEND: The autopay configuration has been suspended. This means it is not active for the moment.
- ACTIVATE: The previously suspended autopay configuration has been re-activated.
- CANCEL: The autopay configuration has been deleted.
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.