Mandate and Mandate Signature

The following documentation describes how to set up, via API, a direct debit mandate linked to a customer as well as the electronic signature of this mandate.

Glossary of key concepts

Before going any further, let’s make sure we’re using the same terminology.

Contact

This is the customer subscribing to the club. To avoid confusion with their potential status (prospect, customer, former customer ...), we will call them contact in this document.

Mandate

The mandate is an authorization to debit the contact’s bank account. It links a club that wishes to collect payments to the bank account that will be debited.

Macro process and prerequisites

As mentioned earlier, you must know the two main parties involved:

• the club
• the contact

The mandate creation and signature process follows these steps:

1. Add the mandate
2. Initiate the signature process via SMS
3. Complete the signature process

Of course, the contact must have a valid mobile phone number to be eligible for electronic signature.

Add the mandate

POST

/{clientToken}/mandates

parameter	description	example
clubId	ID of the club in IRI format	/{clientToken}/clubs/1
contactId	ID of the contact targeted by the mandate. This is an IRI, not just a numeric ID	/{clientToken}/contacts/12345
contactFamilyName	Contact’s last name	Doe
contactGivenName	Contact’s first name	John
contactNumber	Contact’s number	423456
contactAddress[addressCountry]	Country	France
contactAddress[addressLocality]	City	La Madeleine
contactAddress[postalCode]	Postal code	59110
contactAddress[streetAddress]	Street address	41 rue du Général de Gaulle
holder	Account holder	John Doe
iban	Bank account number	DE15843988385047239833
bic	Bank identifier	DEUTDEFF
bank	Bank name	DEUTSCHE BANK AG
validFrom	Start date of mandate validity	2019-06-21

Example

POST /{clientToken}/mandates

Body

{
    "clubId": "/{clientToken}/clubs/22",
    "contactId": "/{clientToken}/contacts/1",
    "contactFamilyName": "Doe",  
    "contactGivenName": "John",  
    "contactNumber": "1",  
    "contactAddress": { 
        "addressCountry": "France",
        "addressLocality": "La Madeleine",
        "postalCode": "59110",
        "streetAddress": "41 Rue du Général de Gaulle"
    },
    "holder": "John Doe",
    "iban": "DE15843988385047239833",
    "bic": "DEUTDEFF",
    "bank": "DEUTSCHE BANK AG",
    "validFrom": "2019-06-21"
}

Response 201 Created

{  
   "@context":"\/clientToken\/contexts\/Mandate",
   "@id":"\/clientToken\/mandates\/373969",         // <-- mandate ID
   "@type":"Mandate",
  // ...
}

Initiate the signature process via SMS

The electronic signature process involves sending an SMS to the contact. This SMS contains a code they must use to validate the signature in the next step.

POST /{clientToken}/signature_requests

parameter	description	example
contactId	Contact ID in IRI format	/{clientToken}/contacts/1
targetId	ID of the mandate to be signed in IRI format	/{clientToken}/mandates/373969

Example

POST /{clientToken}/signature_requests

Body

{
    "contactId": "/{clientToken}/contacts/1",
    "targetId": "/{clientToken}/mandates/373969"
}

Response 201 Created

{  
   "@context":"\/clientToken\/contexts\/SignatureRequest",
   "@id":"\/clientToken\/signature_requests\/3451",         // <-- signature process ID
   "@type":"SignatureRequest",
  // ...
}

Complete the signature process

Once the SMS is received, the application orchestrating the signature must collect the code from the contact targeted by the mandate and complete the signature process by validating this code.

POST

/{clientToken}/signature_requests/{signatureRequestId}/transitions

parameter	description	example
signatureRequestId	ID of the signature process created earlier	3451
transition	Type of transition requested. Possible values are validate or cancel	validate
code	Validation code received by SMS	1234

Example

POST /{clientToken}/signature_requests/3451/transitions

Body

{
    "transition": "validate",
    "code": "94852"
}

Response 201 Created