Mandat et signature de mandat

La documentation suivante décrit la mise en place, via API, d'un mandat de prélèvement attaché à un client ainsi que de la signature dématérialisée de ce mandat.

Glossaire des notions clés

Avant d'aller plus loin, soyons certains que nous parlons des mêmes notions.

Le contact

Il s’agit du client qui s'abonne au club. Pour ne pas confondre avec son éventuel statut (prospect, client, ancien client ...), on le nommera contact dans ce document.

Le mandat

Le mandat est une autorisation de prélèvement sur un compte bancaire du contact. Elle lie donc un club qui souhaite prélever, à un compte bancaire qui sera prélevé.

Macro process et prérequis

Comme indiqué précédemment vous devez connaître les 2 principaux protagonistes :

• le club
• le contact

Le process d'ajout et signature de mandat suit les étapes suivantes:

1. Ajouter le mandat
2. Initier le processus de signature par SMS
3. Terminer le processus de signature

Bien sûr le contact doit posséder un numéro de téléphone mobile valide pour être éligible à la signature dématérialisée.

Ajouter le mandat

POST

/{clientToken}/mandates

paramètre	description	exemple
clubId	Identifiant du club sous forme d'IRI	/{clientToken}/clubs/1
contactId	Identifiant du contact ciblé par le mandat. Il s'agit d'une IRI et non d'un simple identifiant numérique	/{clientToken}/contacts/12345
contactFamilyName	Nom de famille du contact.	Doe
contactGivenName	Prénom du contact.	John
contactNumber	Numéro du contact.	423456
contactAddress[addressCountry]	Pays	France
contactAddress[addressLocality]	Ville	La Madeleine
contactAddress[postalCode]	Code postal	59110
contactAddress[streetAddress]	Adresse	41 rue du Général de Gaulle
holder	Titulaire du compte	John Doe
iban	Numéro du compte bancaire	DE15843988385047239833
bic	Identifiant de la banque	DEUTDEFF
bank	Nom de la banque	DEUTSCHE BANK AG
validFrom	date de début de validité du mandat	2019-06-21

Exemple

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"
}

Réponse 201 Created

{  
   "@context":"\/clientToken\/contexts\/Mandate",
   "@id":"\/clientToken\/mandates\/373969",         // <-- identifiant du mandat
   "@type":"Mandate",
  // ...
}

Initier le processus de signature par SMS

Le processus de signature dématérialisée passe donc par l'envoi d'un SMS au contact. Ce SMS contient un code qu'il devra utiliser pour valider la signature dans l'étape suivante.

POST /{clientToken}/signature_requests

paramètre	description	exemple
contactId	Identifiant du contact sous forme d'IRI	/{clientToken}/contacts/1
targetId	Identifiant du mandat à signer sous forme d'IRI	/{clientToken}/mandates/373969

Exemple

POST /{clientToken}/signature_requests

Body

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

Réponse 201 Created

{  
   "@context":"\/clientToken\/contexts\/SignatureRequest",
   "@id":"\/clientToken\/signature_requests\/3451",         // <-- identifiant du processus de signature
   "@type":"SignatureRequest",
  // ...
}

Terminer le processus de signature

Une fois le SMS reçu l'application souhaitant orchestrer la signature devra récolter le code en provenance du contact ciblé par le mandat et terminer le processus de signature en validant ce code.

POST

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

paramètre	description	exemple
signatureRequestId	Identifiant du processus de signature créé précédemment	3451
transition	Type de transition souhaitée. Les valeurs possibles sont validate ou cancel	validate
code	Code de validation reçu par SMS	1234

Exemple

POST /{clientToken}/signature_requests/3451/transitions

Body

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

Réponse 201 Created