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?
Get in touch with our support department.
Do you have a sales question?
Get in touch with our sales team.
Do you want a global overview of Digiteal ?
Visit the Digiteal website.

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.

Webhooks

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 to and that concern your company. As an integrator, you will receive the notification for all the companies that defined you as integrator.

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 either two options:

  • a link with prefilled information
  • an API call to transfer to Digiteal all the information that you already have to speed up their onboarding process
The easiest way is to give 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. If you want to go the extra mile and really speed things up, you can call the pre-registration API and provide a lot more information.

Company registration link

digiteal-env

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

e-mail

the email address of your client

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

vatNumber

the vat number of your client's company

integratorID

your integrator ID (can be found in your profile)

companyName

the name of your client's company

forBusiness

should be true if you want the company registration page to be displayed but you did not provide either the vatNumber or the companyName

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

Person registration link

digiteal-env

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

e-mail

the email address of your client

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

firstName

the firstName of the person

lastName

the last name of the person

integratorID

your integrator ID (can be found in your profile)

{digiteal-env}/#/register/{e-mail}/?firstName=John&lastName=Doe&integratorID= {ID}

Company pre-registration API

An integrator that wishes to further ease the Digiteal registration process can use an API provided by Digiteal to pre-register a company. This API enables the integrator to send all the information required to perform a complete KYC of the company in Digiteal. The following information is mandatory: vat number, company name, company creation date, email of the contact person. The details of the data to send is described in the CompanyCustomerKYCInfo. The integrator is invited to complete as much information as he can using the following methods:

  • Pre-register the company that takes a CompanyCustomerKYCInfo as JSON payload
  • Send the various documents that takes a multipart/form-data payload to receive documents of type: ID (front and back of the identity document of the contact person), SELFIE_WITH_ID (picture of the contact person with the front of her ID document), BY_LAWS (latest by laws of the company describing the persons that can represent it)
After this information has been provided, the contact person will receive an email inviting her to activate their account. Three reminders will be sent to invite the user to activate his account. The contact person will be able to choose a password and complete her KYC process. Every information missing will be asked during the KYC process. Every information provided will be available after the KYC process to allow the user to review it.

Person pre-registration API

An integrator that wishes to further ease the Digiteal registration process can use an API provided by Digiteal to pre-register a person. This API enables the integrator to send all the information required to perform a complete KYC of the person in Digiteal. Only the email address is mandatory in order to pre-register a person. The details of the data to send is described in the PersonCustomerKYCInfo. The integrator is invited to complete as much information as he can using the following methods:

After this information has been provided, the person will receive an email inviting her to activate their account. Three reminders will be sent to invite the user to activate his account. The person will be able to choose a password and complete her KYC process. Every information missing will be asked during the KYC process. Every information provided will be available after the KYC process to allow the user to review it.

SDD Transfer API

An company or an integrator can transfer the management of their mandates to Digiteal with the SDD Transfer API. This API enables the integrator to send all the information required to perform a complete KYC of a person or a company in Digiteal including the transfer of the mandate. The SEPA Direct Debit (SDD) mandate will be transformed into an automatic payment to give more control to the customer on the withdrawals he will accept. The integrator is invited to complete as much information as he can to further ease the onboarding process of the customer. After this information has been provided, the person/company will receive an email inviting her to activate their account. Three reminders will be sent to invite the user to activate his account. The person/company will be able to choose a password and complete her KYC process. Every information missing will be asked during the KYC process. Every information provided will be available after the KYC process to allow the user to review it.

Registration webhooks

Company registration webhooks

Company webhooks will send you CompanyNotification as JSON payload.

Here are the company webhook types:

  • CREATED: A company has been created.
  • VALIDATED: A company has been validated.
  • UPDATED: A company has been updated.
  • PUT_ON_HOLD: A company has been put on hold.
  • CHANGED_INTEGRATOR: A company has changed integrator.
  • CHANGED_TRUSTED_PAYMENT_INTEGRATOR: A company has changed trusted payment integrator.
  • DELETED: A company has been deleted

Person registration webhooks

Person webhooks will send you PersonNotification as JSON payload.

Here are the person webhook types:

  • CREATED: A person has been created.
  • VALIDATED: A person has been validated.
  • UPDATED: A person has been updated.
  • PUT_ON_HOLD: A person has been put on hold.
  • CHANGED_INTEGRATOR: A person has changed integrator.
  • CHANGED_TRUSTED_PAYMENT_INTEGRATOR: A person has changed trusted payment integrator.
  • DELETED: A person has been deleted

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 2 different ways:

  • 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.

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 document (PDF, XML, RTF,...) to an invoice or a credit note. For example, this document can be a bill but it can also be some energy usage summary or the details of a telephone bill.

This documents should only be attached if the customer choose to receive his invoice/credit note in Digiteal (aka he did an optin). You know that he did an optin by checking if deliveryMethod = S2P in the header of the response to the creation of the invoice / credit note.

Multiple documents can be attached to one invoice/credit note. A document cannot be sent if it is not related to an existing invoice / credit note. Only the emitter of an invoice and his integrator can attach documents to it.

There are two services to send a document. The first one uses the UUID of the invoice/credit note as returned when the invoice / credit note 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.

Credit Notes

This service is used to send a credit note linked to an invoice. For example, this credit note can be for 20 € out of a 100€ invoice.

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.

Force Optin

This service is used to force an optin to Digiteal for a specific customer. The necessary parameters are:

  • the VAT number of the company issuing the invoices
  • the customer internal identifier
  • the email address of the customer

Error codes

200 OK

An empty body response is sent in case of success.

400

BAD_REQUEST:
Some input field is missing or wrong values were provided. The error message will describe which values are incorrect.

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.

Invoice webhooks

Invoice webhooks will send you InvoiceNotification as JSON payload.

Here are the invoice webhook types:

  • PUBLISHED: An invoice been published.
  • READ: An invoice has been read for the first time by the customer.
  • PAID: An invoice has been paid.
  • COMMENTED: A comment has been added to an invoice.
  • UNPAID: An invoice that was paid is now not considered as paid anymore.
  • DOCUMENT_ADDED: A document has been attached to an invoice.
  • CREDIT_NOTE_PUBLISHED: A credit note has been published.
  • CREDIT_NOTE_DOCUMENT_ADDED: A document has been attached to a credit note.

Customer webhooks

Customer webhooks will send you CustomerNotification as JSON payload.

Here are the customer webhook types:

  • OPTIN: A customer did an opt in for a specific channel.
  • OPTOUT: A customer did an opt out for a specific channel.

Peppol Access Point

What is PEPPOL ? PEPPOL enables participants to exchange standards-based electronic documents over the PEPPOL network. Traditional document exchange services are provided by integrators that will send the document based on specific and expensive to operate point-to-point connections. PEPPOL is based on a 4-corner model where the sender has a sending access point and the reciever has a receiving access point. The communication between the sender and the receiver is governed by PEPPOL standards which removes the cost of the point-to-point connections. This way, everyone can be connected to everyone and all the participants can choose a commodity acccess point.

PEPPOL is in use in 32 countries in Europe plus Canada, Singapore and USA with PEPPOL Authorities placed in 12 countries.

PEPPOL is based on three major pillars:

  • the network (PEPPOL eDelivery Network)
  • the document specifications (PEPPOL Business Interoperability Specifications also called "PEPPOL BIS")
  • the legal framework that defines the network governance (PEPPOL Transport Infrastructure Agreements also called the "PEPPOL TIA")

Digiteal is a PEPPOL Access Point certified by the Belgian PEPPOL Authority, operated by the Belgian government. The Belgian PEPPOL Authority manages the list of all their certified PEPPOL Access Points.

For more information about PEPPOL, the country profiles and the access points can be found on the official PEPPOL website.

Which documents are exchanged ? The documents include invoices, credit notes, e-Orders, e-Advance Shipping Notes, eInvoices, eCatalogues, Message Level Responses, etc.

Digiteal supports the following document types:

  • Invoice
  • Credit note
  • Application response
These documents are part of the the PEPPOL BIS Billing process. They are described in the PEPPOL official documentation.

The PEPPOL Access Point API will be available starting in v1.24 of the Digiteal platform.

PEPPOL 4 corner model

PEPPOL registration

Whether you are an ERP, CRM, an accounting package or a Company wishing to send/receive invoices from/to PEPPOL, in order to send or receive invoices through the Digiteal Access Point, you should first become a PEPPOL Integrator. To request the status of PEPPOL Integrator, please contact Digiteal's sales department.

Once registered as a Digiteal PEPPOL integrator, you will have the necessary credentials and authorization to register to receive PEPPOL documents. To receive them for a specific company, please use the register endpoint. To retrieve the registration status of one of the companies that you registered, please use the PEPPOL entity get endpoint. If you wish to stop receiving documents from PEPPOL for a specific company, please use the unregister endpoint.

Send document

The supported documents are described above. In order to send a document, you need to have registered the recipient. Once this is done, you can use the 'PEPPOL send' endpoint.

The best way to integrate PEPPOL is to use the PEPPOL first approach. The rationale behind this approach is that PEPPOL enables automatic exchange of documents and that this exchange is most profitable when a maximum of entities are participating, just like having a phone is more interesting if most people have one. The principals of the PEPPOL first approach are very simple:

  • Whenever you have a document to send that is part of an e-ordering process, first check if the recipient is registered in PEPPOL. You can do this by calling the PEPPOL registry.
  • If the recipient is in the registry, you should send the document using PEPPOL since the fact that he is on the registry means that this is his preferred way of receiving documents, even if you previously were using another way.
  • If the recipient is not in the registry, you should use a fallback mechanism that relies on your own stored contact details to send documents to that recipient.
Of course, all of this process should be automatic.

Send PEPPOL document

The first steps on the Issuer/Integrator side illustrate the PEPPOL first approach.

Receive PEPPOL validation

When you send a PEPPOL Invoice, you will receive a PEPPOL technical confirmation of delivery. The recipient will then manage this invoice and he could send a business response for example to confirm that he accepts or refuses the invoice. This step is optional. That sort of message is called an 'Invoice Response' message. Once you are an authorized PEPPOL integrator and once you have registered to receive PEPPOL documents through the Digiteal Access Point, you will receive calls to your own systems through a PEPPOL notification webhook. The change type will the INVOICE_RESPONSE_RECEIVED.

Receive PEPPOL validation

Receive PEPPOL document

Once you are an authorized PEPPOL integrator and once you have registered to receive PEPPOL documents through the Digiteal Access Point, you will receive calls to your own systems through a PEPPOL notification webhook. The supported documents are described above. Here are the mappings for the change type:

  • INVOICE_RECEIVED: You received an invoice.
  • CREDIT_NOTE_RECEIVED: You received a credit note.

Receive PEPPOL document

Invoicing API details

Invoices API details provides an overview of the provided e-invoicing services and gives a detailed description of the input and output parameters.

Interactive Payments

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.

You can try it out using Digiteal's interactive payment demo application. This demo is linked to Digiteal's test environment so no actual payments will take place there.

API for 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.

QR Code generation

To generate a QR code anonymously, you can do it manually through the QR generator and you can use this base URL to generate them dynamically: https://app.digiteal.eu/api/v1/image-request/slip-image-anonymous (example: https://app.digiteal.eu/api/v1/image-request/slip-image-anonymous?iban=BE72000000001616&billerName=Red%20Cross%20of%20Belgium&amount=1&remittanceInfo=Urgency%20fund&format=qr&language=en). This method is great to showcase but the QR code that is generated can only be used by the mobile banking apps of bank that support the EPC QR code

To enable the payment by QR code for customers from whatever bank in the EU, you can use Digiteal's registered QR code generator. It will still generate a standard EPC QR code but it will also enable the payment from whatever bank in the EU through Digiteal. Here is the procedure to use Digiteal's registered QR code generator (must be done by someone having the signature right of Belfius or through a delegation of power):

  • Create your company account on https://app.digiteal.eu
  • Go through the KYC and pick a "Start" account (cost: 65€)
  • Add the various bank accounts on which you will want to collect
  • Generate the QR code as described here above with the QR generator
  • (optional) if you want, you can also add a payment button so that they can directly pay without going through the QR, for example if they only have a desktop or if they are reaching your donation page on their mobile phone. See the pay button documentation (even easier to integrate through two lines of HTML that you can use on you website but also in an SMS or an email)

The QR generator can interpret the parameters to be prefilled. Here are the various parameters you can use:

  • creditorName: The name of the creditor
  • bic: The BIC of the creditor bank account.
  • iban: The IBAN of the creditor bank account.
  • amount: The amount of the payment. If not provided or set to 0, the customer will be requested to fill in the amount. This can be used for donations to charity for example.
  • creditorReference: The structured reference used to match the payment. This is also called the structured communication in Belgium. Both BBA (Belgium) and ISO (International) types are supported. It can be left empty if the remittanceInfo is defined.
  • remittanceInfo: An unstructured code that is used as communication in the payment. This information is only used if there is no creditorReference. It can be left empty if the creditorReference is defined.
  • email: The email of the person generating the QR code.
  • purpose: The purpose 4 letter code based on the ISO 20022 standard.
  • purposeName: The purpose name based on the ISO 20022 standard.
  • info: The information that should be displayed by the bank based on the EPC guidelines (more info: http://goo.gl/S7LTri). The default value is https://www.scan2pay.info.
  • dueDate: The date before which the payment must be performed. The payment slip will display this date as memo-date. The expected format is YYYY-MM-DD.
  • language: The language in which to display the payment slip. The supported values are en, fr, nl, de. The default value is 'en'.
  • format: Format of the image you want to receive. The supported values are QR, QR_BE, PAYMENT_SLIP, PAYMENT_SLIP_WITH_BANNER, BANNER. The default value is QR.

Here are some sample renderings from the QR generator:

  • Payment slip :
  • QR :
  • QR_BE for a company not registered in Digiteal (new in v1.23) :
  • QR_BE for a company registered in Digiteal (new in v1.23) :
  • Banner :
  • Payment slip with banner (best way to boost conversion):

Sample QR Generator URL with all parameters set (except remittanceInfo)
https://app.digiteal.eu/#/qr-generator?creditorName=Les%20amis%20de%20Demoucelle%20Parkinson%20Charity&bic=BPOTBEB1&iban=BE10000000000404&amount=12.34&creditorReference=014134000443&email=support@digiteal.eu&purpose=CHAR&purposeName=Charity&info=https:%2F%2Fwww.scan2pay.info&dueDate=2030-12-31&language=en&format=PAYMENT_SLIP_WITH_BANNER

Payment webhooks

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.

The Payment Requester API contains a method notificationTransferOfFunds that can be implemented to receive all those push messages.

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 integration easy, fast, robust and most certainly secure.

The pay button itself is context aware which means that the appearance 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 SVG/PNG 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

requesterVAT

the VAT number of your company for which you want to initiate a payment.

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 amountInCents, the iban and the creditorReference or remittanceInfo

iban

The iban where our system will transfer the money to. (only required if invoiceUUID is not 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. When this amount is not provided or set to 0 and if no invoiceUUID was provided, the customer will be requested to fill in the amount he wants to pay. This is useful for donations to charity for example.

language

Defines the language in which the button has to be generated, supported values are NL,FR,EN. Default value is EN.

creditorReference

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

remittanceInfo

The unstructured remittance info of the payment (either this one or the creditorReference is required!) (only required if invoiceUUID is not used). The first name and last name of the debtor will be added to this remittanceInfo.

multiple

(since v1.22) True if you want to accept multiple payments with this description (ex: donate to charity, request a 20€ payment from all the recipients). Default value is false.

type

Determines the format of the image to generate, supported values are PNG and SVG (the default value in PNG)

Pay button Example

<img src="https://app.digiteal.eu/api/v1/payment-request/pay-button?requesterVAT=BE0406729809&amountInCents=4000&iban=BE72000000001616&language=en&remittanceInfo=Urgency%20Fund">
              

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 will see the pre-filled details of the payment, enter his pincode and confirm the payment
  • The payment has already 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.

requesterVAT

the VAT number of your company for which you want to initiate a payment.

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 amountInCents, the iban 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. When this amount is not provided or set to 0 and if no invoiceUUID was provided, the customer will be requested to fill in the amount he wants to pay. This is useful for donations to charity for example.

language

Defines the language in which the button has to be generated, supported values are NL,FR,EN. Default value is EN.

creditorReference

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

remittanceInfo

The unstructured remittance info of the payment (either this one or the creditorReference is required!) (only required if invoiceUUID is not used). The first name and last name of the debtor will be added to this remittanceInfo.

multiple

(since v1.21) True if you want to accept multiple payments with this description (ex: donate to charity, request a 20€ payment from all the recipients). Default value is false.

direct

(since v1.22) True if you want the customer to go through a bank confirmation and reduce the payment delay to 1 day. Extra charges apply for activating this. Default value is false.

confirmationURL

The url where the user will be redirected once he will click to go back to the origin website after a successful payment. If no URL is provided, he will go back to the invoice list in Digiteal.

errorURL

The url where the user will be redirected once he will click to go back to the origin website after the payment was cancelled or an error occured. If no URL is provided, he will go back to the invoice list in Digiteal.

Pay button Example

          <a href="https://app.digiteal.eu/api/v1/payment-request/pay-button/execute?requesterVAT=BE0406729809&amountInCents=4000&iban=BE72000000001616&language=en&remittanceInfo=Urgency%20Fund" style="outline: none;">
            <img src="https://app.digiteal.eu/api/v1/payment-request/pay-button?requesterVAT=BE0406729809&amountInCents=4000&iban=BE72000000001616&language=en&remittanceInfo=Urgency%20Fund">
            </a>
              
Payment screen

B2B Creditor Button

B2B Creditor button

The B2B Creditor button allows the debtor to pay a creditor company using the same simple solution as the payment button. This solution allows you to pay a specific creditor even if the creditor company is not registered in Digiteal yet. When an invoice is received, the creditor button can be built using the metadata of the invoice.

In case of a KNOWN creditor, (=registered in Digiteal):

  1. Pay the amount for the received invoice by clicking on the b2b creditor button and validating with the pincode
  2. The money is transferred to the Digiteal Account.
  3. Once received on the Digiteal Account, the money is transferred to the Creditor Account and the debtor is notified (through mail or webhook)

In case of an UNKNOWN creditor,(= not registered in Digiteal):

  1. Pay the amount for the received invoice by clicking on the b2b creditor button.
  2. Once the payment has been confirmed by the pincode, the creditor company will be contacted through mail.
    The b2b creditor button applies the same interaction as the pay button and indicates that the invoice is paid but remains unconfirmed.
    The amount received by Digiteal will be kept on the account of Digiteal.
  3. When the company registers on Digiteal and activates his bank account (=validating that he is the owner of the creditor bank account), the money will be transferred.
  4. When the money is sent out, the debtor company will receive a notification and the button will also change appearance.
  5. If the creditor company does not register within 5 business days, the money will be reimbursed to the debtor.

Schematic overview of b2b creditor payment
B2B creditor button (still to pay)
B2B creditor button (payment executed but creditor not yet registered)
B2B creditor button (payment executed and creditor registered + activated account)

B2B Creditor button generation

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

The response of the url can be 4 different SVG images

  • Payment has not been paid :
  • Payment has been paid but not unconfirmed :
  • Payment has been paid :
  • The platform is unavailable: a message will be shown explaining that the payment is currently unavailable

debtorVAT

the VAT number of the debtor company that will pay the invoice

creditorVAT

the VAT number of the creditor company you want to pay.

creditorName

Provide the company name of the creditor company. This name will be automatically filled in when the company goes to the registration page.

creditorIBAN

The creditor iban that is present on the invoice.

creditorEmail

the email address of the creditor.

amountInCents

The amount of the payment expressed in cents without comma.

language

Defines the language in which the button has to be generated, supported values are NL,FR,EN

creditorReference

the structured creditor reference of the payment (either this one or the remittanceInfo is required!)

remittanceInfo

the unstructured remittance info of the payment (either this one or the creditorReference is required!)

confirmationURL

once the payment is confirmed the debtor will be redirected to this url

errorURL

if an error occured during the payment the debtor will be redirected to this url

B2B creditor button Example

<a id="execute" rel="nofollow" href="https://test.digiteal.eu/api/v1/payment-request/b2b-pay-button/execute?creditorVAT=BE555554325&creditorName=CompanyB&debtorVAT=BE0897227828&remittanceInfo=18124&creditorEmail=companyB@yopmail.com&creditorIBAN=BE68130191571783&amountInCents=52109&language=EN">
 <img id="image" src="https://test.digiteal.eu/api/v1/payment-request/b2b-pay-button?creditorVAT=BE555554325&creditorName=CompanyB&debtorVAT=BE0897227828&remittanceInfo=18124&creditorEmail=companyB@yopmail.com&creditorIBAN=BE68130191571783&amountInCents=52109&language=EN"></a>
              

B2B Creditor button execute

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

calling this url will result in a redirect to the Digiteal payment platform.

debtorVAT

the VAT number of the debtor company that will pay the invoice

creditorVAT

the VAT number of the creditor company you want to pay.

creditorName

Provide the company name of the creditor company. This name will be automatically filled in when the company goes to the registration page.

creditorIBAN

The creditor iban that is present on the invoice.

creditorEmail

the email address of the creditor.

amountInCents

The amount of the payment expressed in cents without comma.

language

Defines the language in which the button has to be generated, supported values are NL,FR,EN

creditorReference

the structured creditorReference of the payment (either this one or the remittanceInfo is required!)

remittanceInfo

the unstructured remittanceInfo of the payment (either this one or the creditorReference is required!)

confirmationURL

once the payment is confirmed the debtor will be redirected to this url

errorURL

if an error occured during the payment the debtor will be redirected to this url

B2B creditor button Example

<a id="execute" rel="nofollow" href="https://test.digiteal.eu/api/v1/payment-request/b2b-pay-button/execute?creditorVAT=BE555554325&creditorName=CompanyB&debtorVAT=BE0897227828&remittanceInfo=18124&creditorEmail=companyB@yopmail.com&creditorIBAN=BE68130191571783&amountInCents=52109&language=EN">
 <img id="image" src="https://test.digiteal.eu/api/v1/payment-request/b2b-pay-button?creditorVAT=BE555554325&creditorName=CompanyB&debtorVAT=BE0897227828&remittanceInfo=18124&creditorEmail=companyB@yopmail.com&creditorIBAN=BE68130191571783&amountInCents=52109&language=EN"></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.

Auto Payment webhooks

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.

The Payment Requester API contains a method notificationConfigChange that can be implemented to receive all those push messages.

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.

Trusted payment introduction

Whenever you require a payment that should only be executed when a certain condition is met, you can use the Digiteal trusted payment solution. The transfer will take place only if the condition is met. If it isn't, the payment will be reimbursed in full to the original debtor after the transfer expiration date. Two conditions can be used:

  • amount: If the total amount of the payments linked to this transfer has reached the maximum amount associated with the transfer, it will be transferred directly. Three days after the end of the transfer expiry, if the minimal amount of the transfer has been reached, it will also be transferred.
  • third party confirmation: The trusted third party that created the transfer can validate or invalidate it. If it has been validated, the transfer will be executed immediately. If it has been validated, the transfer will be reimbursed immediately.

The typical trusted payment follows these steps:

  • Creation: The trusted payment integrator creates the transfer either through a call to the API or using the Digiteal platform UI. The parameters of the payment are the release condition, the minimum and maximum amount of the transfer, the end date, the creditor and his account. The creditor but have set the integrator as trusted payment integrator. The outcome of this creation step is a configured trusted payment with a defined creditor reference.
  • Incoming payment(s): The integrator communicates the creditor references and requests the debtor(s) to transfer the money to the Digiteal trusted account (BIC: GKCCBEBB, IBAN: BE40 0689 0629 4063) using a usual bank transfer (SEPA Credit Transfer or SCT) with the provided creditor reference.
  • Validation: The condition to execute the payment is met either by a call to the API for the paymens requiring a third party confirmation or if the maximum amount is met. Another condition to executing the payment is if the minimum amount is reached at the latest 3 days after the end of the payment end date.
  • Payment: The payment is executed through a SEPA Credit Transfer (SCT) from Digiteal's trusted account to the creditor.

Trusted payment webhooks

When something happens linked to a trusted payment, the Digiteal platform will notify the debtor, the creditor and/or the 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 debtor/creditor/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 debtor/creditor, you will received the notifications for the webhooks you registered too and that concern your company. As a trusted payment integrator, you will receive the notification for all the companies that defined you as trusted payment integrator.

Trusted payment webhooks will send you TransferOfFundsNotification as JSON payload.

The webhooks that you can register to are:

  • TRANSFER_PAYMENT_RECEIVED: A payment has been received for a trusted payment.
  • TRANSFER_PAYMENT_STARTED: A trusted payment execution has started. The money transfer order to the creditor will soon be executed.
  • TRANSFER_PAYMENT_COMPLETED: A trusted payment execution has completed. The money has arrived on the account of the creditor.
  • TRANSFER_REIMBURSMENT_STARTED: A trusted payment reimbursement has started. The money transfer order to the debtor will soon be executed.
  • TRANSFER_REIMBURSEMENT_COMPLETED: A trusted payment reimbursement has completed. The money has arrived on the account of the debtor.

As you can see in the state diagram, apart from the happy flow, the payment can go into many other flows. To summarize them, the payment can either

  • not be linked to a trusted payment (for example if it is a debtor error) in which case it will be reimbursed to the debtor or linked to a specific trusted payment after confirmation by the debtor
  • be too risky to execute, in which case it will be reimbursed to the debtor
  • not reach the release condition after the end date, in which case it will be reimbursed to the debtor
The trusted payments states are described here:

Trusted payment API details

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