Generate an authorization for a mandate

Generate an authorization to allow your company to create and use mandates using your own SDD creditor identifier. Manage those authorizations with Digiteal and download a proof of authorization validated by the debtor.

Request an authorization

A request call is made to Digiteal giving information about the creditor and the debtor of the mandate. Digiteal will validate the user's access to it's own bank account and request him to consent to the authorization allowing you to create and use a mandate to debit his account.

Most of the debtor information must be provided when creating the request but some information are optional. The IBAN, if not provided, will be collected by Digiteal. You will be able to retrieve that IBAN through the notification once the authorization process is complete.

SDD Creditor Identifier

The Creditor Identifier is a uniform and standardized identification field used throughout Europe that identifies the creditor.

This identifier must be provided in the request, paired with a unique mandate number it will act as the key for the authorization and used throughout the API to manage the authorization.

AIS

Digiteal uses AIS to verify that the user can access the bank account linked to the mandate and therefore that the user is allowed to give you access this account.
The user will be redirected to the environment of his bank and authenticates to the system before giving Digiteal access to his bank account information.

Flow description

As a response of an authorization request you will receive a URL to redirect the user to the request flow. The first part of this flow is to ask the user for an AIS consent and then collect the missing user's personal information before redirecting him to his banking environment.

1224

Bank selection and consent

In the bank environment the user will be asked to authenticate and to accept that Digiteal access certain information on his account.

804

Bank environment

Finally the user is asked for a mandate consent. After this step, the authorization document is generated and the user is redirected to a success page or to the successUrl if defined.

394

Mandate consent

Mock Bank

In TEST you will always be redirected to the Mock Bank environment no matter which bank is selected. This allows you to test the flow without having to use real bank information. To grant access to the Mock Bank bank account you must use the provided IBAN and login using the credentials below.

πŸ“˜

Mock Bank credentials

IBAN: BE89549452327885
username: [email protected]
password: 123tagadaM

If you wish to use IBANs from other countries, please see the complete list of credentials here.

Redirect Urls

You can define a set of redirect URL to redirect the user after completing the request flow.

URLDescription
successUrlUsed in case of a successful flow.
errorUrlUsed in case of a technical error making it impossible for the user to continue the flow.
failureUrlUsed if the authorization could not be granted due to a problem with the user's information (ie. the user do not have access to the specified bank account).

You can find details about the failure in the URL query parameter code:
- INVALID_IBAN: the user does not have access to the bank account.
- INVALID_OWNER: the debtor named in the request is not an owner of the bank account.
cancelUrlUsed if the user cancel the flow.

You can find details about the cancellation in the URL query parameter code:
- AIS_CONSENT: the flow was cancelled when asking for AIS consent.
- BANK_ENV: the flow was cancelled in the bank environment.
- MANDATE_CONSENT: the flow was cancelled when asking for consent to use a mandate.
- TIMEOUT: the flow was cancelled automatically after a certain time if the user did not complete it.

Webhook

You can subscribe to a webhook to be notified when the flow is completed. You can then retrieve the status of the request, relevant information related to that status and the collected IBAN of the debtor.
The webhook will also contains the requestId for you to link with the corresponding request.

πŸ“˜

Webhook type

MANDATE_AUTHORIZATION_STATUS

You can override the default webhook URL using the notificationUrl attribute of the request if you wish to change the default behaviour of the webhook.

🚧

notificationUrl cannot be defined without an existing webhook.

You can find the details of the webhook payload in the callback section of the request authorization endpoint.

Document

After a successful flow, a PDF document signed by Digiteal is generated and serve as proof that the user allowed the use of a mandate on his account.

You can generate a temporary link to download that document. This link is available for 15 min and publicly available to anyone with whom it is shared.

791

Here is an example of the document generated after a successful flow.

Delete an authorization

Once a mandate is revoked or not in use, you should clean the system by deleting the authorization . This action will remove all information about the authorization from Digiteal and delete the generated document as well.