Signing

E-mandates via Twikey

566 views August 20, 2018 August 7, 2019 3

Overview

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.

User experience

End-user

  1. Merchants can invite their customers (debtors) via a link.
  2. 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.
  3. 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).
  4. Signicat informs the merchant of the acceptance of the mandate or contract.
  5. Optionally, the debtor can also cancel and modify mandates or contracts via their Creditor Portal.
  6. 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.

SAML

The following is the basic URL for triggering an e-mandate signing session in the pre-production environment:
https://eu01.preprod.signicat.com/std/method/signicat/?id=twikey::&target=https%3A%2F%2Feu01.preprod.signicat.com%2Fjames%2Fresponse&prefilled.ct=1482

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:

Attribute-key Attribute-value Type
ct

(Mandatory)

Contract Template ID Number (*)
l The language choice to be pre-selected on the registration screen String (en/nl/fr/de/it/es/pt)
email 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

String

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.

OIDC

The following examples use the https://eu01.preprod.signicat.com/ environment as an example.
First of all, the following URL is used to redirect the user to Twikey and, finally, to labs.signicat.com:

https://eu01.preprod.signicat.com/oidc/authorize?response_type=code&scope=address+profile+email+openid&client_id=demo-preprod-basic&redirect_uri=https%3A%2F%2Flabs.signicat.com%2Fnotifications%2Fhome%2Freceive&acr_values=urn%3Asignicat%3Aoidc%3Amethod%3Atwikey&signicat_profile=default&state=1234&login_hint=ct-1482

The URL will contain an authorization code, such as in:

https://labs.signicat.com/notifications/home/receive?code=<CODE>&state=1234&session_state=a33faf7806602f4f1f1fd54dac871522e0ccdb82f52252563a7614645a3f1874._xW7-tL-tZgLnHk3

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:

login_hint=ct-1482&login_hint=email-user123@gmail.com

This selects the contract template 1482 and fills the email field with user123@gmail.com. Full example:

https://eu01.preprod.signicat.com/oidc/authorize?response_type=code&scope=address+profile+email+openid&client_id=demo-preprod-basic&redirect_uri=https%3A%2F%2Flabs.signicat.com%2Fnotifications%2Fhome%2Freceive&acr_values=urn%3Asignicat%3Aoidc%3Amethod%3Atwikey&signicat_profile=default&state=1234&login_hint=ct-1482&login_hint=email-user123@gmail.com

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

  1. Go to https://www.beta.twikey.com/r/admin#/c/contracts.
  2. Click on Settings ->Templates.
  3. In the top right corner, press “New”.
  4. Fill out the form with the already known “default” data.
  5. “Type” combobox will determine the type of scheme to be used: CORE or B2B.
  6. Make sure to specify the exit URL. This will be the URL the end-user is redirected to after finishing the mandate process.
  7. 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:

 

 

Was this helpful?