An e-mandate is a digital authorization for one or more direct debit payments.
What is (SEPA) direct debit?
Within the EU, consumers and companies can agree to pay for goods or services using direct debit. This means that you as an end-user (the debtor) allow, via e-mandate, that someone (the creditor) can take money from your bank account. Direct debit has been standardized in the EU to enable cross-border use, and is therefore called “SEPA direct debit” (SDD) in the EU.
- The e-mandate is managed by the creditor (the party receiving the money).
- There are two SEPA Direct Debit (SDD) types: Core and B2B. The main difference is that with B2B the creditor can be sure that he can keep the money under any condition (the debtor has no refund rights). More details can be found in the SDD Core Rulebook and the SDD B2B Rulebook.
What is a (SEPA) e-mandate?
The e-mandate is the approval for the direct debit, and is standardized in the EU. The standard can be found here.
Signicat’s solution, powered by our partner Twikey, supports e-mandates for the Netherlands and Belgium.
- In the Netherlands, SDD is implemented as “Incasso” and the e-mandate as Incassomachtigen.
- In Belgium, SDD is called “Europese domiciliëring. It is well described here.
- Merchants can invite their customers (debtors) via a link.
- When the debtor opens the link, a screen with input fields is shown. These input fields can be prefilled (see Attribute-key below). If an emailaddress is prefilled, the Twikey form will not be shown to the debtor and the debtor will instead proceed to the step below.
- The debtor:
- In the Netherlands:
- If the bank supports “Incassomachtigen”, the debtor chooses his/her bank and then approves the mandate via the flow as delivered by the bank. Following authorisation, the debtor is routed back to the creditor’s online environment (for an example, click here).
- If the bank does not support “Incassomachtigen”, the debtor selects “Another bank?” and is guided through a process where they can give their mandate on paper.
- In Belgium: the end user fills in their IBAN, approves the mandate, for example with their eID card (for an example, click here, signing starts at minute 1:10).
- In the Netherlands:
- Signicat informs the merchant of the acceptance of the mandate or contract.
- Optionally, the debtor can also cancel and modify mandates or contracts via their Creditor Portal.
- Optionally, Twikey can also create Direct Debit files, deliver them to a bank and follow up reporting. This service is currently not supported by Signicat.
Creditor (Signicat customer)
Twikey delivers a Creditor management portal for each individual creditor.
On the management portal, a creditor can:
- Create and send e-mandates to debtors
- Monitor e-mandate statuses
- Cancel, resume, and reschedule (recurring) direct debits
- Check the direct debit collection statuses (optional)
- Configure “templates” which define:
- Which methods can be used to sign an e-mandate
- The end-user UX
- Which creditor bank account should be used to receive the funds
- One-time or recurring payment
- The redirect URL
Creating an e-mandate URL
Currently, Signicat only supports debtors signing e-mandates.
Other Twikey functionality (e.g. update a mandate, cancel a mandate, retrieve a PDF of a mandate) is not supported via Signicat’s APIs. These functions are available via the Twikey dashboard.
The following is the basic URL for triggering an e-mandate signing session in the pre-production environment:
Please note the query string &prefilled.ct=1482 at the end of the URL. This represents the Contract Template number and is the only mandatory field in the call.
You can follow the same approach of adding &prefilled.<ATTRIBUTE-KEY>=<ATTRIBUTE-VALUE> for other attributes. These attributes will then be asked for in the mandate form presented to the end-user:
|Contract Template ID||Number (*)|
|l||The language choice to be pre-selected on the registration screen||String (en/nl/fr/de/it/es/pt)|
|The email to be pre-filled on the registration screen||String|
|lastname||The last name of the person to be pre-filled on the registration screen||String|
|firstname||The first name of the person to be pre-filled on the registration screen||String|
|address||The address (street + number) of the debtor||String|
|city||The city to be pre-filled on the registration screen||String|
|zip||The zip to be pre-filled on the registration screen||String|
|country||The country to be pre-filled on the registration screen||String (Iso2)|
|mobile||The mobile phone number to be pre-filled on the registration screen (optional)||String|
|mandateNumber||Mandate ID overruling the automatically generated number by Twikey. Needs to be unique.||String (Uppercase)|
|contractNumber||The contract number which can override the one defined in the template||String|
|iban||The IBAN account number to be pre-filled in the contract||String|
|bic||The BIC number to be pre-filled in the contract (if known)||String|
|amount||Amount to add to the mandate once the debtor has signed the mandate||Double|
|token||A parameter that can be returned in the exit URL (see below) to avoid invalid sessions||String|
|attributename||If attributes are defined, the name of the attribute||String|
|plan||name of a plan in order to add a (custom) plan to the mandate||String|
|Parameters if the debtor is a company (B2B mandate)|
|company||enable ‘I act on behalf of a company’ on the registration screen. By default, the checkbox value is false.||Boolean|
|companyName||the company name (of the customer) to be pre-filled on the registration screen||String|
|vatno||the enterprise number (of the customer) to be pre-filled on the registration screen||String|
|form||Legal form of the company (depending on country). If the form given in the URL is not known, Twikey will interpret it as “other” value.
• BE : nvsa, bvbasprl, vzwasbl, cvsc
• NL : nv, bvba, cv, cvoa, vof
• FR : sa, sarl, sc, snc, eurl
• LU : sa, sarl, senc, soparfi
• DE : ag, gmbh, gbr, kg, ev, kgaa, ohg
• IT : spa, srl, sa, sapa, sas, snc
• UK : plc, ltd
After an e-mandate is signed, a SAML 1.1 response is returned to the creditor, containing the fields specified in the URL, adding the template-specific fields. The mandate information is also available in the Creditor Management Portal. In the pre-production environment, the response is available in OIDC and SAML2.0 as well.
The URL will contain an authorization code, such as in:
With that authorization code, run the following cURL:
curl -X POST \ https://eu01.preprod.signicat.com/oidc/token \ -H 'Authorization: Basic YOUR_BASE64_CREDENTIALS_clientid_AND_clientsecret_jwt' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code&code=<CODE>&redirect_uri=https%3A%2F%2Flabs.signicat.com%2Fnotifications%2Fhome%2Freceive&client_id=<client_id>'
As a response, you will receive a JSON object containing an access_token. Use that access_token as bearer in the next cURL call to the userinfo endpoint, which is used to retrieve the user information related to Twikey’s eMandate:
curl -X POST \ https://eu01.preprod.signicat.com/oidc/userinfo \ -H 'Authorization: Bearer <ACCCESS_TOKEN> \ -H 'Content-Type: application/x-www-form-urlencoded' \
As the SAML version, OIDC is also capable of receiving input parameters to prefill Twikey’s initial form. In order to prefill the Twikey form, the login_hint field can be used:
This selects the contract template 1482 and fills the email field with email@example.com. Full example:
Creating a mandate contract template (CT) with Twikey
For every type of mandate, Twikey allows the creditor to create a template which contains more information, such as B2B, creditor ID, one-off, contract reference and description. This must be manually configured in the creditor GUI. Twikey provides a unique ID per contract template (CT).
- Go to https://www.beta.twikey.com/r/admin#/c/contracts.
- Click on Settings ->Templates.
- In the top right corner, press “New”.
- Fill out the form with the already known “default” data.
- “Type” combobox will determine the type of scheme to be used: CORE or B2B.
- Make sure to specify the exit URL. This will be the URL the end-user is redirected to after finishing the mandate process.
- You will be presented with a popup similar to the following:
A sample flow
1. Redirect the user to the mandate signing URL, e.g. https://eu01.preprod.signicat.com/std/method/signicat/?id=twikey::&target=https%3A%2F%2Feu01.preprod.signicat.com%2Fjames%2Fresponse&prefilled.ct=1482. The user will see a field where he/she needs to upload his/her details to sign the mandate:
2. After filling out the form, the user is asked for consent:
3. The user needs to select a signing method to sign the mandate:
4. In the bank simulation screen, choose the “Success (w/o delay)” scenario:
5. The SAML response is received: