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.
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.
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.
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.
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.
In the bank environment the user will be asked to authenticate and to accept that Digiteal access certain information on his account.
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.
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
username: [email protected]
If you wish to use IBANs from other countries, please see the complete list of credentials here.
You can define a set of redirect URL to redirect the user after completing the request flow.
|successUrl||Used in case of a successful flow.|
|errorUrl||Used in case of a technical error making it impossible for the user to continue the flow.|
|failureUrl||Used 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.
|cancelUrl||Used 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.
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.
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.
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.
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.