S-money API

Create a direct debit top-up

Hadassa — 2017-03-17T11:35:35Z

To create a direct debit top-up, please have a look at the example in the right margin.

The mandatory parameters are:
orderid
mandate
amout
ismine

Precision : Expect a delay between the debit of the paying bank account and the credit of the beneficiary user account.

Send the data of the top-up made by a third-party server

The third-party server needs to provide the S-money server with an url server, so that the S-money server can communicate the direct debit top-up validation (within 3 to 6 business days).

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

The parameters of the HTTP request are:

Parameters	Type	Description
id	string	Transfer operation reference in the third-party application (orderid)
error	Int	Error code for failed payments, 0, if no errors.
type	Int	Operation type 7 = direct debit top-up
status	Int	Operation status -1 = unknown 0 = en attente 1 = completed 2 = refunded 3 = refused 4 = waiting for validation
sequencenumber	Int	Direct debit sequence number (if multiple direct debit)
userid	String	User identifier in the third-party application
userstatus	Int	User status 0 = Not confirmed 1 = OK 2 = Frozen 3 = On the fly 4 = Being closed 5 = Closed

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

{
 "orderid":"xh02",
 "mandate":{"id":123},
 "amount":1000,
 "fee":300,
 "paymentdate":"2014-01-13T00:00:00.000000+02:00",
 "beneficiary":{"appaccountid":"123"},
 "ismine":true,
 "message":"Prélèvement bancaire"

}

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

{
 "id":2, 
 "orderid":"xh02",
 "mandate":{
 "id":123,
 "href":"/api/[domaine_partenaire]/mandates/123"
 },
 "amount":1000, 
 "fee":300,
 "beneficiary":{
 "id":98,
 "appaccountid":"123",
 "displayname":"Jean Dupont",
 "href":"/api/[domaine_partenaire]/users/{appuserid}/subaccounts/123"
 },
 "ismine":true, 
 "message":"Prélèvement bancaire",
 "creationdate":"2014-01-10T15:49:58.791121+02:00",
 "paymentdate":"2014-01-13T00:00:00.000000+02:00",
 "status":0,
 "schedules":null,
 "motif":"echeance-avril"

}

Modify a direct debit

Hadassa — 2016-07-06T15:55:04Z

To modify a direct debit, please have a look at the example in the right margin.

Error cases

HTTP code	Error code	Explication
404	356	Operation cannot be found

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

{
 "amount":420, 
 "paymentdate":"2014-09-01T00:00:00.000000+02:00",
 "fee":90 

}

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

{
 "id":2, 
 "orderid":"xh02",
 "mandate":
 {
 "id":123,
 "href":"/api/[domaine_partenaire]/mandates/123"
 }, 
 "amount":420,
 "fee":90,
 "beneficiary":
 {
 "id":98,
 "appaccountid":"123",
 "displayname":"Jean Dupont",
 "href":"/api/[domaine_partenaire]/users/{appuserid}/subaccounts/123"
 },
 "ismine":true, 
 "message":"Prélèvement bancaire",
 "creationdate":"2014-01-10T15:49:58.791121+02:00",
 "paymentdate":"2014-09-01T00:00:00.000000+02:00",
 "status":0,
 "schedules": null,
 "motif":"echeance-avril"

}

Cancel a direct debit

Hadassa — 2016-07-06T15:52:33Z

To cancel a direct debit, please have a look at the example in the right margin.

Error cases

HTTP code	Error code	Explication
404	356	Operation cannot be found

Request
PUT /api/domaine_partenaire/users/appuserid/payins/directdebits/orderid/
Accept: application/vnd.s-money.v1+json
Content-Type: application/vnd.s-money.v1+json
Authorization: Bearer ACCESS_TOKEN

{
 "status":5

}

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

{
 "id":2, 
 "orderid":"xh02",
 "mandate":
 {
 "id":123,
 "href":"/api/[domaine_partenaire]/mandates/123"
 }, 
 "amount":1000,
 "fee":300,
 "beneficiary":
 {
 "id":98,
 "appaccountid":"123",
 "displayname":"Jean Dupont",
 "href":"/api/[domaine_partenaire]/users/{appuserid}/subaccounts/123"
 },
 "ismine":true, 
 "message":"Prélèvement bancaire",
 "creationdate":"2014-01-10T15:49:58.791121+02:00",
 "paymentdate":"2014-01-13T00:00:00.000000+02:00",
 "status":5,
 "schedules": null,
 "motif":"echeance-avril"

}

Retrieve a direct debit top-up

Hadassa — 2016-07-06T12:02:33Z

To retrieve a direct debit top-up, please have a look at the example in the right margin.

To retrieve a direct debit top-up on a domain-level, the URL will be: GET/api/[domaine_partenaire]/payins/directdebits

To retrieve a user direct debit top-up, the URL will be:
Pour récupérer le chargement par prélèvement d'un utilisateur, l'URL sera : GET/api/[domaine_partenaire]/users/appuserid/payins/directdebits

Error cases:

HTTP code	Error code	Explication
404	356	Operation cannot be found

Request :
GET /api/[domaine_partenaire]/payins/directdebits/orderid 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":2, 
 "orderid":"xh02",
 "mandate":{
 "id":123,
 "href":"/api/[domaine_partenaire]/mandates/123"
 }, 
 "amount":1000,
 "fee":300,
 "beneficiary": {
 "id":98,
 "appaccountid":"123",
 "displayname":"Jean Dupont",
 "href":"/api/[domaine_partenaire]/users/{appuserid}/subaccounts/123"
 },
 "ismine":true, 
 "message":"Prélèvement bancaire",
 "creationdate":"2014-01-10T15:49:58.791121+02:00",
 "paymentdate":"2014-01-13T00:00:00.000000+02:00",
 "status":0,
 "schedules":null,
 "motif":"echeance-avril"

}

Retrieve the list of direct debit top-ups

Hadassa — 2016-07-06T11:01:35Z

To retrieve the list of direct debit top-ups, please have a look at the example in the right margin.

To retrieve the list of direct debit top-ups on a domain-level, the URL will be:
GET /api/[domaine_partenaire]/payins/directdebits

To retrieve the list of a user direct debit top-ups, the URL will be:
GET /api/[domaine_partenaire]/users/appuserid/payins/directdebits

Request :
GET /api/[domaine_partenaire]/payins/directdebits 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":2, 
 "orderid":"xh02",
 "mandate":{
 "id":123,
 "href":"/api/[domaine_partenaire]/mandates/123"
 }, 
 "amount":1000,
 "fee":300,
 "beneficiary":{
 "id":98,
 "appaccountid":"123",
 "displayname":"Jean Dupont",
 "href":"/api/[domaine_partenaire]/users/{appuserid}/subaccounts/123"
 },
 "ismine":true, 
 "message":"Prélèvement bancaire",
 "creationdate":"2014-01-10T15:49:58.791121+02:00",
 "paymentdate":"2014-01-13T00:00:00.000000+02:00",
 "status":0, 
 "schedules":null,
 "motif":"echeance-avril"

},{…}]

Resources

Hadassa — 2016-07-06T10:50:31Z

The recovery of direct debit top-up can be done through:

/api/[domaine_partenaire]/users/AppUserId/payins/directdebits
OR
/api/[domaine_partenaire]/users/AppUserId/mandates/mandateid/directdebits

1.DirectDebits

Contains the information about a direct debit top-up

Property	Type	Example	Description
Id	Long	123	Top-up ID
OrderId	String	xh02	Payment identifier in the third-party application
CreationDate	DateTime	2014-01-10T15:49:58. 791121+02:00	Top-up creation date
PaymentDate	DateTime	2014-01-13T00:00:00. 000000+02:00	Expected date of a top-up (between 3 and 6 business days from the creation date)
Amount	Long	2350	Top-up amount (in cents)
Fee	Long		Fee amount (the property "amount" does not include the fee amount)
Status	Int	1	Top-up status 0 = Waiting 1 = Completed 2 = Refunded 3 = Failed 4 = Waiting for validation 5 = Cancelled
Beneficiary	SubAccountRef		Item containg the details of the recipient sub-account. If not precised, it is the main account of the connected user which is used
IsMine	Bool	True	True if the account holder is also the bank account holder (it is a top-up, and not a payment)
Message	String		Payment message (limited to 140 caracters)
Mandate	MandateRef		Mandate reference used for direct debit
Schedules	PaymentSchedule		Table of installments (more installments for direct debit)
Motif	String	echeance-avril	Reason for the debit

2.SubaccountRef

This item allows to identify the accounts between which the operations are made.

Property	Type	Example	Description
Id	Long	98	Account identifier
AppAccountId	String	"123"	Account identifier provided by the third-party application
DisplayName	String	"Jean Dupont"	Display account name
Href	Uri	"/api/[domainePartenaire] /accounts/123"	Uri for the account details

3.BankAccountRef

This item allows to identify the user's bank account.

Property	Type	Example	Description
Id	Long	98	Bank account identifier
Href	Uri	"/api/[domainePartenaire] /bankaccounts/98"	Uri for details of the bank account

4.MandateRef

This item allows to identify a direct debit mandate

Property	Type	Example	Description
Id	Long	45	Mandate ID
Href	Uri	"/api/[domainePartenaire] /mandates/45"	Uri for mandate details

Modifier un prélèvement

Hadassa — 2016-05-02T11:34:14Z

Pour modifier un prélèvement référez-vous à l'exemple présent dans la marge de droite.

Cas d'erreurs

Code HTTP	Code erreur	Explication
404	356	Opération introuvable

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

{
 "amount":420, 
 "paymentdate":"2014-09-01T00:00:00.000000+02:00",
 "fee":90 

}

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

{
 "id":2, 
 "orderid":"xh02",
 "mandate":
 {
 "id":123,
 "href":"/api/[domaine_partenaire]/mandates/123"
 }, 
 "amount":420,
 "fee":90,
 "beneficiary":
 {
 "id":98,
 "appaccountid":"123",
 "displayname":"Jean Dupont",
 "href":"/api/[domaine_partenaire]/users/{appuserid}/subaccounts/123"
 },
 "ismine":true, 
 "message":"Prélèvement bancaire",
 "creationdate":"2014-01-10T15:49:58.791121+02:00",
 "paymentdate":"2014-09-01T00:00:00.000000+02:00",
 "status":0,
 "schedules": null,
 "motif":"echeance-avril"

}

Annuler un prélèvement

Hadassa — 2016-05-02T11:28:17Z

Pour annuler un prélèvement référez-vous à l'exemple présent dans la marge de droite.

Cas d'erreur

Code HTTP	Code erreur	Explication
404	356	Opération introuvable

Requête
PUT /api/domaine_partenaire/users/appuserid/payins/directdebits/orderid/
Accept : application/vnd.s-money.v1+json
Content-Type : application/vnd.s-money.v1+json
Authorization : Bearer ACCESS_TOKEN

{
 "status":5

}

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

{
 "id":2, 
 "orderid":"xh02",
 "mandate":
 {
 "id":123,
 "href":"/api/[domaine_partenaire]/mandates/123"
 }, 
 "amount":1000,
 "fee":300,
 "beneficiary":
 {
 "id":98,
 "appaccountid":"123",
 "displayname":"Jean Dupont",
 "href":"/api/[domaine_partenaire]/users/{appuserid}/subaccounts/123"
 },
 "ismine":true, 
 "message":"Prélèvement bancaire",
 "creationdate":"2014-01-10T15:49:58.791121+02:00",
 "paymentdate":"2014-01-13T00:00:00.000000+02:00",
 "status":5,
 "schedules": null,
 "motif":"echeance-avril"

}

Récupérer un chargement par prélèvement

Axel — 2015-07-28T17:15:58Z

Pour récupérer un chargement par prélèvement référez-vous à l'exemple présent dans la marge de droite.

Pour récupérer un chargement par prélèvement au niveau du domaine, l'URL sera : GET /api/[domaine_partenaire]/payins/directdebits

Pour récupérer le chargement par prélèvement d'un utilisateur, l'URL sera : GET /api/[domaine_partenaire]/users/appuserid/payins/directdebits

Cas d'erreurs :

Code HTTP	Code erreur	Explication
404	356	Opération introuvable

Requête :
GET /api/[domaine_partenaire]/payins/directdebits/orderid 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":2, 
 "orderid":"xh02",
 "mandate":{
 "id":123,
 "href":"/api/[domaine_partenaire]/mandates/123"
 }, 
 "amount":1000,
 "fee":300,
 "beneficiary": {
 "id":98,
 "appaccountid":"123",
 "displayname":"Jean Dupont",
 "href":"/api/[domaine_partenaire]/users/{appuserid}/subaccounts/123"
 },
 "ismine":true, 
 "message":"Prélèvement bancaire",
 "creationdate":"2014-01-10T15:49:58.791121+02:00",
 "paymentdate":"2014-01-13T00:00:00.000000+02:00",
 "status":0,
 "schedules":null,
 "motif":"echeance-avril"

}

Récupérer la liste des chargements par prélèvement

Axel — 2015-07-28T17:14:52Z

Pour récupérer la liste des chargements par prélèvement référez-vous à l'exemple présent dans la marge de droite.

Pour récupérer la liste des chargements par prélèvement au niveau du domaine, l'URL sera : GET /api/[domaine_partenaire]/payins/directdebits

Pour récupérer la liste des chargements par prélèvement d'un utilisateur, l'URL sera : GET /api/[domaine_partenaire]/users/appuserid/payins/directdebits

Requête :
GET /api/[domaine_partenaire]/payins/directdebits 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":2, 
 "orderid":"xh02",
 "mandate":{
 "id":123,
 "href":"/api/[domaine_partenaire]/mandates/123"
 }, 
 "amount":1000,
 "fee":300,
 "beneficiary":{
 "id":98,
 "appaccountid":"123",
 "displayname":"Jean Dupont",
 "href":"/api/[domaine_partenaire]/users/{appuserid}/subaccounts/123"
 },
 "ismine":true, 
 "message":"Prélèvement bancaire",
 "creationdate":"2014-01-10T15:49:58.791121+02:00",
 "paymentdate":"2014-01-13T00:00:00.000000+02:00",
 "status":0, 
 "schedules":null,
 "motif":"echeance-avril"

},{…}]