S-money API

Sign an electronic mandate

Hadassa — 2016-12-08T16:45:06Z

1. Send the details of the mandate request to the S-money server

To sign a mandate, please have a look ath the example in the right margin.

The urlcallback is an optional parameter.

2. Send the details of the electronic mandate created by the third-party server

The third-party server should provide the S-money server with an url, which allows the S-money server to communicate the results of the mandate validation.

The HTTP POST method is used to invoke the S-money server.

HTTP request parametres are :

Parameter	Type	Description
id	Long	Mandate ID
error	Int	Error code for failed requests 0 = No error. 1 = Session failed 2 = Session interrupted 3 = Session cancelled
type	Int	Operation type 9 = mandate creation
status	Int	Mandate status 1 = Validated 2 =Dismissed 3 = Failure

3. Redirection at the end of an electronic mandate signature

The third-party server should provide the S-money server with an url allowing the S-money server to redirect the client to the third-party environment.

The url can be either associated to a web scheme (http/https) or a private scheme where the request will be made from the third-party mobile application.

These are the HTTP request parametres:

Parameter	Type	Description
id	Long	Mandate ID
type	Int	Operation type 9 = mandate creation
status	Int	Mandate status 1 = Validated 3 = Failure

Request :
POST /api/[domaine_partenaire]/users/appuserid/mandates HTTP/1.1
Accept: application/vnd.s-money.v1+json
Content-Type: application/vnd.s-money.v1+json
Authorization: Bearer ACCESS_TOKEN

{
 "bankaccount":{
 "id":1
 },
 "urlreturn":"http://test.com/returnurl/",
 "urlcallback":"http://test.com/callbackurl/"

}

Response :
HTTP/1.1 201 CREATED
Content-Type: application/vnd.s-money.v1+json
Location: /api/[domaine_partenaire]/users/appuserid/mandates/id

{
 "href":"{URL à appeler}",
 "id":123,
 "bankaccount":{
 "id":1,
 "href":"/api/[domaine_partenaire]/users/{appuserid}/bankaccounts/1"
 },
 "date":"2013-09-10T15:49:58.791121+02:00",
 "status":0,
 "errorcode" : 0,
 "UMR": "30007-Sandbox-66673-14032016-0"

}

Signer un mandat électronique

Hadassa — 2016-12-08T16:45:04Z

1. Envoi des données de la requête de mandat au serveur S-money

Pour signer un mandat électronique, référez-vous à l'exemple présent dans la marge de droite.

L'urlcallback est un paramètre optionnel.

2. Envoi des données du mandat électronique créé au serveur tiers

Le serveur tiers doit mettre à disposition une url serveur permettant au serveur S-money de le notifier du résultat de la validation du mandat.

L'appel du serveur S-money est effectué en méthode HTTP POST.

Les paramètres de la requête HTTP sont :

Paramètre	Type	Description
id	Long	Id du mandat
error	Int	Code d'erreur pour les demandes échouées 0 = Aucune erreur. 1 = Echec de la session 2 = Session avortée 3 = Session annulée
type	Int	Type de l'opération 9 = création d'un mandat
status	Int	Statut du mandat 1 = Validé 2 = Révoqué 3 = Echec

3. Redirection en fin de signature électronique du mandat

Le serveur tiers doit mettre à disposition une url serveur permettant au serveur S-money de rediriger le client vers l'environnement tiers.

L'url peut-être soit associée au scheme web (http/https) ou à un scheme privatif dans le cas où l'appel serait effectué à partir d'une application mobile tierce.

Les paramètres de la requête HTTP sont :

Paramètre	Type	Description
id	Long	Id du mandat
type	Int	Type de l'opération 9 = création d'un mandat
status	Int	Statut du mandat 1 = Validé 3 = Echec

Requête :
POST /api/[domaine_partenaire]/users/appuserid/mandates HTTP/1.1
Accept : application/vnd.s-money.v1+json
Content-Type : application/vnd.s-money.v1+json
Authorization : Bearer ACCESS_TOKEN

{
 "bankaccount":{
 "id":1
 },
 "urlreturn":"http://test.com/returnurl/",
 "urlcallback":"http://test.com/callbackurl/"

}

Réponse :
HTTP/1.1 201 CREATED
Content-Type : application/vnd.s-money.v1+json
Location : /api/[domaine_partenaire]/users/appuserid/mandates/id

{
 "href":"{URL à appeler}",
 "id":123,
 "bankaccount":{
 "id":1,
 "href":"/api/[domaine_partenaire]/users/appuserid/bankaccounts/1"
 },
 "date":"2013-09-10T15:49:58.791121+02:00",
 "status":0,
 "errorcode" : 0,
 "UMR": "30007-Sandbox-66673-14032016-0"

}

Revoke a mandate

Hadassa — 2016-07-07T10:52:21Z

To revoke a mandate, please refer to the example in the right margin of this page.

Request :
PUT /api/[domaine_partenaire]/users/appuserid/mandates/id HTTP/1.1
Accept: application/vnd.s-money.v1+json
Content-Type: application/vnd.s-money.v1+json
Authorization: Bearer ACCESS_TOKEN

{
 "status":2

}

Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.s-money.v1+json

{
 "id":123,
 "bankaccount":{
 "id":1,
 "href":"/api/[domaine_partenaire]/users/{appuserid}/bankaccounts/1"
 },
 "date":"2013-09-10T15:49:58.791121+02:00",
 "status":2,
 "errorcode" : 0,
 "UMR": "30007-Sandbox-66673-14032016-0"

}

Retrieve a mandate

Hadassa — 2016-07-07T10:50:55Z

To retrieve a mandate, please have a look at the example in the right margin.

Request :
GET /api/[domaine_partenaire]/mandates/id
OR GET /api/[domaine_partenaire]/users/appuseridmandates/id HTTP/1.1
Accept: application/vnd.s-money.v1+json
Authorization: Bearer ACCESS_TOKEN

Recovery of electronic mandate
Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.s-money.v1+json

{
 "id":123,
 "bankaccount":{
 "id":1,
 "href":"/api/[domaine_partenaire]/bankaccounts/1"
 },
 "date":"2013-09-10T15:49:58.791121+02:00",
 "status":1,
 "errorcode" :0,
 "UMR": "30007-Sandbox-66673-14032016-0"

}

Recovery of paper mandate
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.s-money.v1+json

{
 "MandateDemands": [
 {
 "Id": 123,
 "RequestDate": "2016-03-24T09:05:18",
 "Status": 1,
 "Reason": null,
 "VoucherCopies": [
 {
 "Id": 456,
 "Name": "fichier mandat",
 "ContentType": "application/pdf",
 "Size": 81277,
 "href":"/ api/[domaine_partenaire]/mandates/123/attachments/456"
 },

{…}

] 

}

],
 "Id": 789,
 "Date": "2016-03-24T09:02:20",
 "BankAccount": {
 "id":1,
 "href":"/api/[domaine_partenaire]/bankaccounts/1"
 },
 "Status": 0,
 "ErrorCode": 0,
 "UMR": "30007-Sandbox-66673-14032016-0"

}

Récupération mandat en format PDF
Request :
GET /api/[domaine_partenaire]/users/appuserid/mandates/id
Authorization: Bearer ACCESS_TOKEN
Accept: application/pdf

Retrieve the list of mandates

Hadassa — 2016-07-07T10:48:15Z

To retrieve the list of mandates, please have a look at the example in the right margin.

Request :
GET /api/[domaine_partenaire]/mandates
OR /api/[domaine_partenaire]/users/appuserid/mandates HTTP/1.1
Accept: application/vnd.s-money.v1+json
Authorization: Bearer ACCESS_TOKEN

Response :
HTTP/1.1 200 OK
Content-Type: application/vnd.s-money.v1+json

[{
 "id":123,
 "bankaccount":{
 "id":1,
 "href":"/api/[domaine_partenaire]/bankaccounts/1"
 },
 "date":"2013-09-10T15:49:58.791121+02:00",
 "status":1,
 "errorcode" : 0,
 "UMR": "30007-Sandbox-66673-14032016-0"

},{…}]

Send a paper mandate to S-money

Hadassa — 2016-07-07T10:46:38Z

To send a paper mandate, please have a look at the example in the right margin.

If a mandate is refused for X reason, it is possible to make a new request uploading a new document on the same id of the mandate (id of a refused mandate).

If a mandate is refused for X reason, the reason is sent via « reason » parameter and the status of the mandate is 0 (waiting).

1. Sending the details of a mandate created by the third-party server
The third-party sever should provide the S-money server with an url allowing the S-money server to communicate the result of the mandate validation (within 2 business days after the receipt of the request).

The HTTP POST method is used to invoke the S-money server.
The HTTP request parameters are:

Parameter	Type	Description
id	Long	Mandate ID
type	Int	Operation type 9 = mandate
mandatedemandstatus	Int	Request status 0 = Incompleted 1 = Waiting 2 = Refused 3 = Accepted
status	Int	Mandate status 0 = waiting 1 = validated 2 = revoked
userid	string	User identifier in the third-party application
reason	String	Reason of refusal: The bank account of the mandate does not match the registered bank account Mandate not readable The mandate is not signed Other (xxxxxxxx)

Request
POST /api/[domaine_partenaire]/users/appuserid/mandates/id/attachments HTTP/1.1
Accept: application/vnd.s-money.v1+json
Content-Type: multipart/form-data; boundary= ------------------------- acebdf13572468
Authorization: Bearer ACCESS_TOKEN

---------------------------acebdf13572468 

Content-Disposition: form-data; name="file1"; filename="img1.png"

Content-Type: image/png

[FILE CONTENT]

---------------------------acebdf13572468

Response
HTTP/1.1 201 CREATED
Content-Type: application/vnd.s-money.v1+json
Location: /api/[domaine partenaire]/users/appuserid/mandates/183/attachments/id

Resources

Hadassa — 2016-07-07T10:35:44Z

Retrieving madates associated with a user is made via:

/api/[domaine_partenaire]/mandates to access debit mandates associated with the connected user

/api/[domaine_partenaire]/users/appuserid/mandates to access debit mandates associated with the user "appuserid".

There are two ways to create a bank debit mandate:
Mandate by electronic signature, validated by electronic signature
Mandate on paper, validated by S-money Back Office.

1.Mandates
Contains details of a bank debit mandate

Parameter	Type	Example	Description
Id	Long	123	Mandate ID
Date	DateTime	2013-09-10T15:49:58. 791121+02:00	Mandate date of creation
BankAccount	BankAccountRef		Reference to the bank account
Status	Int	0	Mandate status 0 = Pending 1 = Validated 2 = Dismissed 3 = Failure
UrlReturn	String	http://s-money.fr/returnurl	URL to which the user is redirected after the signature
MandateDemands	MandateDemands		Request details
Href	Uri		URL to call in order to electronically sign the mandate
ErrorCode	Int	0	Error code for failed requests, 0 = No error 1 = Session failed 2 = Session interrupted 3 = Session cancelled
UMR		30007-Sandbox-66673-14032016-0	Mandate Single Reference

2. MandateDemands
Contains details of a bank debit mandate

Parameter	Type	Example	Description
Id	Long	123	Request ID
RequestDate	DateTime	2013-09-10T15:49:58. 791121+02:00	Date of the creation of the request
VoucherCopies	List<Attachement>		List of supporting documents
Status	Int		Request status 0 = Incomplete 1 = Waiting 2 = Refused 3 = Accepted
Reason	String		Reason of refusal : The mandate bank account do not match the registered bank account The mandate is unreadable The mandate is not signed Other ( xxxxxxxx )

3. Attachement
This object identifies the user bank account

Parameter	Type	Example	Description
Id	Long	98	Document ID
Name	String	Receipt	File name
ContentType	String	"image/png"	Image type
Size	Long	523010	Size of the attached file (in octet)
Href	Url		Link to the attached file

4. BankAccountRef
This object identifies the user bank account

Parameter	Type	Example	Description
Id	Long	98	Bank account ID
Href	Uri	"/api/[domaine_partenaire]/bankaccounts/98"	Url to the bank account details

Révoquer un mandat

Hadassa — 2016-05-02T12:30:11Z

Pour révoquer un mandat, veuillez vous référer à l'exemple présent en marge de droite.

Requête :
PUT /api/[domaine_partenaire]/users/appuserid/mandates/id HTTP/1.1
Accept : application/vnd.s-money.v1+json
Content-Type : application/vnd.s-money.v1+json
Authorization : Bearer ACCESS_TOKEN

{
 "status":2

}

Réponse :
HTTP/1.1 200 OK
Content-Type : application/vnd.s-money.v1+json

{
 "id":123,
 "bankaccount":{
 "id":1,
 "href":"/api/[domaine_partenaire]/users/{appuserid}/bankaccounts/1"
 },
 "date":"2013-09-10T15:49:58.791121+02:00",
 "status":2,
 "errorcode" : 0,
 "UMR": "30007-Sandbox-66673-14032016-0"

}

Récupérer un mandat

Hadassa — 2016-05-02T12:28:22Z

Pour récupérer un mandat, veuillez vous référer à l'exemple présent en marge de droite.

Requête :
GET /api/[domaine_partenaire]/mandates/id
OU GET /api/[domaine_partenaire]/users/appuseridmandates/id HTTP/1.1
Accept : application/vnd.s-money.v1+json
Authorization : Bearer ACCESS_TOKEN

Récupération mandat électronique
Réponse :
HTTP/1.1 200 OK
Content-Type : application/vnd.s-money.v1+json

{
 "id":123,
 "bankaccount":{
 "id":1,
 "href":"/api/[domaine_partenaire]/bankaccounts/1"
 },
 "date":"2013-09-10T15:49:58.791121+02:00",
 "status":1,
 "errorcode" :0,
 "UMR": "30007-Sandbox-66673-14032016-0"

}

Récupération mandat papier
Réponse
HTTP/1.1 200 OK
Content-Type : application/vnd.s-money.v1+json

{
 "MandateDemands": [
 {
 "Id": 123,
 "RequestDate": "2016-03-24T09:05:18",
 "Status": 1,
 "Reason": null,
 "VoucherCopies": [
 {
 "Id": 456,
 "Name": "fichier mandat",
 "ContentType": "application/pdf",
 "Size": 81277,
 "href":"/ api/[domaine_partenaire]/mandates/123/attachments/456"
 },

{…}

] 

}

],
 "Id": 789,
 "Date": "2016-03-24T09:02:20",
 "BankAccount": {
 "id":1,
 "href":"/api/[domaine_partenaire]/bankaccounts/1"
 },
 "Status": 0,
 "ErrorCode": 0,
 "UMR": "30007-Sandbox-66673-14032016-0"

}

Récupération mandat en format PDF
Requête :
GET /api/[domaine_partenaire]/users/appuserid/mandates/id
Authorization : Bearer ACCESS_TOKEN
Accept : application/pdf

Récupérer la liste des mandats

Hadassa — 2016-05-02T12:22:03Z

Pour récupérer la liste des mandats, veuillez vous référer à l'exemple présent en marge de droite.

Requête :
GET /api/[domaine_partenaire]/mandates
OU GET /api/[domaine_partenaire]/users/appuserid/mandates HTTP/1.1
Accept : application/vnd.s-money.v1+json
Authorization : Bearer ACCESS_TOKEN

Réponse :
HTTP/1.1 200 OK
Content-Type : application/vnd.s-money.v1+json

[{
 "id":123,
 "bankaccount":{
 "id":1,
 "href":"/api/[domaine_partenaire]/users/{appuserid}/bankaccounts/1"
 },
 "date":"2013-09-10T15:49:58.791121+02:00",
 "status":1,
 "errorcode" : 0,
 "UMR": "30007-Sandbox-66673-14032016-0"

},{…}]