Top-up by cheque

Generalities

1.1 How does it work?

The partner has to create a reference of top-up by cheque with S-money. This reference enables linking the S-money account.

When creating this reference, the S-money server send back:
- The reference to write on the cheque
- The adress to send the cheque to.

Thus the partner has to ask his client:
- To write a cheque to S-money
- To add the reference (on the back of the cheque or after S-money in the order
- To send to the adress received.

The partner will be notified:
- When the cheque has been received
- When the cheque has been credited form the account.

Warning: Multiple cheques with the same reference can credit the account linked to this reference.

1.2 Macro Process

Ressources

To create or retrieve transfers references associated with a user:

/api/[domaine_partenaire]/users/AppUserId/chequereferences
/api/[domaine_partenaire]/users/AppUserId/payins/cheques/references

To retrieve a specific reference:

/api/[domaine_partenaire]/users/AppUserId/chequereferences/id
/api/[domaine_partenaire]/users/AppUserId/chequereferences/reference
/api/[domaine_partenaire]/users/AppUserId/payins/cheques/references/id
/api/[domaine_partenaire]/users/AppUserId/payins/cheques/references/reference

To retrieve the list of top-ups by transfers of a user:

/api/[domaine_partenaire]/users/AppUserId/payins/cheques

To retrieve the list of top-ups by transfer of a user associated with a reference:

/api/[domaine_partenaire]/users/AppUserId/payins/cheques?reference=reference

To retrieve a user top-up by transfer:

/api/[domaine_partenaire]/users/AppUserId/payins/cheques/id

2.1 References

Contains the information of a cheque reference

Parameters Type Example Description
Id Long 123 Reference ID
Beneficiary SubAccountRef Object with the receiving sub-account details.

If not mentioned, the main sub-account of the connected user is used
IsMine Bool True True if the account holder is also the bank account holder

(it is an account top-up, and not a payment)
Reference String "A1B2C3D4E5" Reference to write on the cheque
BankAccount BankAccount Details of the account to which the client has to make a transfer

2.2 Cheques

Contains the information of a top-up by cheque

Parameters Type Example Description
Id Long 123 Top-up ID
PaymentDate DateTime 2013-09-10T15:49:58.791121+02:00 Transfer date
Amount Long 2350 Amount of the top-up (in cents)
Status Int 1 Payment status
0 = Pending
1 = Realised
2 = Refunded
3 = Failure
4 = Waiting for validation
5 = Canceled
6 = Waiting for a remittance
Beneficiary SubAccountRef Object with the receiving sub-account details.

If not mentioned, the main sub-account of the connected user is used
IsMine Bool True True if the account holder is also the bank account holder

(it is an account top-up, and not a payment)
Reference String "A1B2C3D4E5" Reference to write on the cheque
Address Address Details of the account to which the client has to make a transfer

2.3 SUBACCOUNTREF

This object enables identifying the accounts between which the operations are made.

Parameter Type Example Description
Id Long 98 Account ID.
AppAccountId String "123" ID of the account provided by the third-party application.
DisplayName String "John Smith" Account displayed name
Href Uri "/api/[domaine_partenaire]/accounts/123" Uri to the account details

2.4 ADDRESS

Parameter Type Example Description
Name String S-money - cheque-cashing departement of the platform xxx Name + Department to comunicate to the client to send the cheque
Street String 2 rue des chataîgners Number and street
Zipcode String 75001 Zip code
City String Paris Town
Country String "FR" Country (code ISO 3166-1)

Ask for a reference of a top-up by cheque

3.1 Send data of the request of top-up by cheque to the S-money server

To ask for a reference of a top-up by cheque, please refer to the example in the right margin.

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

The third-party server has to make available a server url enabling the S-money server to notify it of the result of the processing of a top-up.

Warning, multiple top-ups can come with the same reference.

Calling the S-money server is done using the HTTP POST method.

Parameters of the HTTP request are:

Parameters Type Description
id Long Top-up operation ID
reference String Cheque reference
error Int Error code for failed top-ups, 0 if no failure.
type Int Operation type
12 = top-up by cheque
status Int Operation status
-1 = unknown
0 = pending
1 = completed
2 = refunded
3 = refused
4 = waiting for validation
5 = canceled
6 = waiting for a remittance
userid String ID of the user in the third-party application
userstatus Int User status
0 = Not confirmed
1 = OK
2 = Frozen
3 = On the fly
4 = Closing
5 = Closed

Retrieve the list of references of top-ups by cheque

To retrieve the list of references of top-ups by cheque, please refer to the example in the right margin.

Retrieve a reference of top-up by cheque

To retrieve a reference of top-up by cheque, please refer to the example in the right margin.

Error case

HTTP CodeError codeExplication
404 822 This transfer reference does not really exist.

Retrieve the list of the top-ups by cheque

To retrieve the list of top-ups by cheque, please refer to the example in the right margin.

Retrieve a top-up by cheque

To retrieve a top-up by cheque, please refer to the example in the right margin.

Error case:

Code HTTP Error code Explication
404 356 Operation cannot be found