Documentation

Overview

API Basics

The API is a RESTful Web Services with JSON formatted messages.

Basicaly, it means that :

    • Submiting new data is performed with HTTP POST request
    • Retreiving existing data is performed with HTTP GET request
    • Modifying existing data is performed with HTTP PUT request
    • Removing or canceling existing data is performed with HTTP DELETE request

All requests must be sent setting the header CONTENT-TYPE at "application/json".

Environments

Production environment: https://emoney-services.w-ha.com

Test / pre-production environment: https://test-emoney-services.w-ha.com

End-point : /api/

Both environments use HTTPS standards with TLS 1.2.

Details informations (certificat chain, supported cyphers list...) about our certificats can be obtained through Qualys SSL Labs website.

Authentication

All requests require to be fully authenticated through the http header « Authorization ». The content of the header should respect the format decribed below.

All the requests must be sent from your server directly to our server and not from a user's browser or application.

For security reasons, the API Access Key and Secret Key provided by W-HA must be stored securely in your server. It should never be accessible or visible to the end-users.

It should not be stored or packaged in any source codes accessible from end-user point of view (html/javascript from a browser or in a source code of an application for Smartphone).

Authorization Header

AUTHORIZATION: AUTH API_ACCESS_KEY:TIMESTAMP:VERSION:SIGN

 Property

Type

Value

Description                                                                

api_access_key

string

size = 16

API Key (provided by W-HA)

timestamp

long

Should not be aged of more than 5 minutes.

Timestamp of the request in milliseconds

version

integer


Version number of the authentication process

sign

string


HMAC-SHA256 signature

Signature computation

The “sign” parameter is a HMAC-SHA256 of the following parameters separated by « : » :

  • api_access_key,
  • timestamp,
  • version,
  • request body (could be empty in some cases).

A secret shared key (provided by W-HA) called “api_secret_key” is used to compute the hash.

  • StringToSign = api_access_key:timestamp:version:request_body
  • Sign = HMAC-SHA256(StringToSign, api_secret_key)


Example with a request body
  • api_access_key = OLqMu27t1mylpc2D
  • api_secret_key = YMy7t54-WaF9F!LOSp994p1?0x8pUp
  • timestamp = 1494862655078
  • version = 1
  • request_body = {"tag":"my_new_tag"}
  • StringToSign = OLqMu27t1mylpc2D:1494862655078:1:{"tag":"my_new_tag"}
  • Sign = 2b6cf86e9f3d5c50a5b7f79aa10c9ce6da1fcd31211bf87374347274c168cf01
HTTP Header
Authorization: AUTH OLqMu27t1mylpc2D:1494862655078:1:2b6cf86e9f3d5c50a5b7f79aa10c9ce6da1fcd31211bf87374347274c168cf01
Example with no request body
  • api_access_key = OLqMu27t1mylpc2D
  • api_secret_key = YMy7t54-WaF9F!LOSp994p1?0x8pUp
  • timestamp = 1494862788453
  • version = 1
  • request_body =
  • StringToSign = OLqMu27t1mylpc2D:1494862788453:1:
  • Sign = 1e8b319599fa2185b55e502ed962490e9e23aceb920676e17c0ac76112d5450a
HTTP Header
Authorization: AUTH OLqMu27t1mylpc2D:1494862788453:1:1e8b319599fa2185b55e502ed962490e9e23aceb920676e17c0ac76112d5450a

Versioning

Minor API modifications that are not breaking the compatibility with the existing API should be supported transparently by the partner.

Example of non-breaking changes:

  • adding new API endpoint/service
  • adding some optional parameters in request header, query or body of existing API
  • adding some optional new properties in the response header or body of existing API
  • adding new possible values in ENUM parameters of a request
  • changing the order of properties in a response
  • changing human-readable strings such as error message
  • changing size or format of generated ids (object identifier) but respecting the documented maximal size


Major API modifications breaking the compatibility will be managed through a new version number in the API URL.

Example of breaking changes:

  • renaming or removing existing endpoint/service
  • renaming or adding mandatory parameters in the request header, query or body
  • renaming or removing parameters in response header or body
  • restricting allowed values of an ENUM in a request

Lists Pagination Management

Some Web Services return a list of elements (i.e GET /wallets return a list of Wallets).

Responses of these services are based on a pagination mechanism to control the number of returned elements.

By default, the response is the first page and the maximum number of returned elements is 20.

This behavior can be changed for a resquest by setting the following parameters :

URL - Parameters

Type

Value

Description                                                                

page

integer

min = 1

optional, default = 1

Requested page index

per_page

integer

min = 1

max = 100

optional, default = 20

Maximum of element number per page

The response HTTP body contains the list of elements and the response HTTP header includes the following properties:

Header - Property

Type

Description
x-pageintegerRequested page index (equals to the request parameter page if it is set)
x-page-sizeintegerCapacity for a page (equals to the request parameter per_page if it is set)
x-total-elementslongThe overall amount of elements corresponding to the search criteria (without pagination)
x-total-pagesintegerThe number of pages corresponding to the search criteria

Error management

If a request failed, HTTP status code of the response is different of 200 (or associated 201, 204 ...) and the body contains an error object structuring the detailed cause of the problem.

HTTP error code

Code

Description

400 Bad request

See error code / message in response body.

401 Authentication failure

Authentication failed.

403 Forbidden

Authentication is OK but you are not authorized to access this method.

404 Not found

Error on hostname or URI.

405 Method not allowed

Wrong utilization of the method (e.g. GET instead of POST).

500 The server encountered an unexpected condition

In case of internal error.

501 Not Implemented

Not supported.

503 Server busy and service unavailable

Service temporary unavailable. Try later.

Error Object

Object

ERROR

Property

Type

Value

Description

code

string

size = 4

Error code

message

string

max size = 300

Error message

Sample
HTTP/1.1 400 Bad Request
{
    "code": "1004",
    "message": "Invalid parameter(s)"
}

List of Error codes

Code
Message
HTTP Status Code
9001

Internal error

500



1001

Unknown service version

400

1002

Authorization error

401

1003

Service forbidden

403
1005

Invalid request JSON format

400
1006

Invalid request parameter(s)

400



2001Unknown Wallet id '<id>'400
2002Wallet '<id>' invalid status: <status>400
2003Wallet '<id>' invalid type: <type>400
2004

Operation not permitted because balance=<balance>

400



2101Operation not permitted.400



2201Unknown Account id '<id>'400
2202Account '<id>' invalid status: <status>400
2203

Account '<id>' invalid type: <type>

400
2204Account '<id>' invalid kyc level: <level>400
2205Invalid Country code '<code>'400
2206Invalid Birthdate - Minimum age required is <age>400
2211Operation not permitted because Account Validation is in progress400
2212

Account information and kyc level '<level>' are not consistent, infos: <information>

400
2213Requested Level '<level>' must be greater than current '<current_level>'400



2231Unknown Document id '<id>'400
2232Document '<id>' invalid status: <status>400



2301Unknown BankAccount id '<id>'

400

2302BankAccount '<id>' invalid status: <status>400



2351Unknown CreditCard id '<id>'400
2352CreditCard '<id>' invalid status: <status>400



2401Unknown Transaction id '<id>'400
2402Transaction '<id>' invalid status: <status>400
2403Transaction '<id>' invalid type: <type>400
2404Transaction '<id>' invalid payment method: <payment_method>400

2405

Invalid parameters: fees are greater than amount400
2406Invalid parameters: fees wallet id is missing400
2407Invalid parameters: sender wallet '<wallet_id>' (account ''<account_id>') and bank account '<bankaccount_id>' (account '<account_id>') are not associated to the same account400
2408Invalid parameters: transaction partner ref '<partner_ref>' invalid (must be unique)400
2409Invalid parameters: sender and receiver are equals400
2420Transaction '<id>' cannot be confirmed as authorization is timed-out since <date>400
2421Transaction '<id>' authorization failure400
2422Transaction '<id>' confirmation failure400
2423Transaction '<id>' cancellation failure400
24Transaction '<id>' refund failure400
2425Transaction '<id>' refund impossible as it is a REFUND transaction400



2451The cash-out amount from a partner Wallet cannot be less than '<maxAmount>'400
2452Wallet '<id>' insufficient balance.400
2461Account '<id>' has reached is BALANCE MAX limit400
2462Account '<id>' has reached is CASH_IN MONTHLY MAX limit400



2702Transaction Credit Card '<id>' malformed URL: <url>400



8001Invalid Currency Code '<code>'400
8002Invalid Country Code '<code>'400

KYC Compliance

Account STANDARD


LEVEL_0
LEVEL_1
LEVEL_2
LEVEL_3
Mandatory dataEmail or mobile phone number

Level_0 data

Lastname

Firstname

Birthdate

Level_1 data

Nationality

Home Address or Residence Country


A valid bank account

Level_2 data

Home Address

Documents

Proof of id

Proof of iban


Prood of address

Notice that a Wallet cannot be created for an account at LEVEL_0. This type of account could only be used for payment (cash-in to another wallet) and for end-user credit card storage.

If lastname, firstname and birthdate are provided, the account is automatically updated to LEVEL_1 and the creation of a wallet is possible.


LEVEL_0
LEVEL_1
LEVEL_2
LEVEL_3

Maximal Balance

0 €250 € (1)10 000 € (1)100 000 €

Maximal Cash-in

(per calendar month)

n/a

250 € (1)


100 000 € (1) 

1 000 000 €

(1) If one of this limits is exceeded, the account's status is automatically set at "KYC_REQUIRED". Then, the e-money is blocked, neither cash-out nor transfer-out is allowed, until the account is successfully upgraded to the next LEVEL.

Notice that, in such case, cash-in or transfer-in are allowed but within the following maximal balance :

  • 2 500 € for LEVEL_1 account
  • 25 000 € for LEVEL_2 account

Notice that those limits are for an account over all its wallets (the sum of all transactions over all the account's wallets should respect the limits).

Notice that the transfer and cash-out are also limited by the minimum balance of a wallet (0€).


Account BUSINESS



LEVEL_1
LEVEL_2
Mandatory data

Entity Name

Business Type

Registration Number

Representative Firstname, Lastname, Birthdate

Entity email

Representative Nationality

Entity Address


A valid bank account

Optional data

Representative Nationality

Entity Address

Documents

Proof of registration

Representative's Proof of id

Proof of address

Proof of iban



LEVEL_1
LEVEL_2

Maximal Balance


250 € (1)10 000 000 €

Maximal Cash-in

(per calendar month)

250 € (1)


100 000 000 €

(1) If one of this limits is exceeded, the account's status is automatically set at "KYC_REQUIRED". Then, the e-money is blocked, neither cash-out nor transfer-out is allowed, until the account is successfully upgraded to the next LEVEL.

Notice that, in such case, cash-in or transfer-in are allowed but within the following maximal balance :

  • 2 500 € for LEVEL_1 account

Notice that those limits are for an account over all its wallets (the sum of all transactions over all the account's wallets should respect the limits).

Notice that the transfer and cash-out are also limited by the minimum balance of a wallet (0€).

Account Services

Create an account - Standard

Service to create a new Standard account.

REQUEST

Operation:   POST /accounts/standard

Body-Property

Type

Value

Description

subscriberSUBSCRIBERoptionalUser personal information
address

ADDRESS

optionalResidence address
email

string

max size = 128

optional (1)

Email

phone_numberstring

max size = 14

digits only

optional (1)

Phone number

tagstring

max size = 100

optional

Field used by partner to set some customized information

(1): Email or Phone number is required.

Request Sample
POST /accounts/standard
{
    "subscriber" :{
        "lastname" : "Martin",
        "firstname" : "Philippe",
        "birthdate" : "1986-03-01",
        "nationality" : "FRA"
    },
    "address" :{
        "label1" : "12 rue de Stalingrad",
        "zip_code" : "92800",
        "city" : "Puteaux",
        "country" : "FRA"
    },
    "email" : "m.philippe@wha.fr",
    "tag" : "account_type1"
}


RESPONSE

HTTP statusCase
201
Success
Body-PropertyTypeValueDescription
id

string

max size = 64

Account id

Response Sample
HTTP/1.1 201 CREATED
{
    "id": "AS-459652557845695458"
}


Create an account - Business

Service to create a new Business account.

REQUEST

Operation:   POST /accounts/business

Body-Property

Type

Value

Description

namestringmax size = 64Organization name
business_typeenum
  • COMPANY
  • ASSOCIATION
  • SOLE_TRADER

optional, default = COMPANY

Type a business
email

string

max size = 128

Organization email

phone_number

string

max size = 12

digits only

international format (without 00 or + prefix)

optional

Phone number

registration_numberstringmax size = 128

SIRET for COMPANY or ASSOCIATION

License number for SOLE_TRADER

representative

REPRESENTATIVE


Representative information
addressADDRESSoptionalOrganization address
tagstringmax size = 100Field used by partner to set some customized information
Request Sample
POST /accounts/business
{
    "name" : "Association Sportive P10",
    "business_type" : "ASSOCIATION",
    "email" : "asw.contact@wha.fr",
    "registration_number" : "100018757",
    "phone_number" : "33129541388",
    "representative" : {
        "lastname" : "Julien",
        "firstname" : "Dore",
        "birthdate" : "1970-12-01",
        "nationality" : "FRA"
    },
    "address" : {
        "label1" : "88 rue Barthe",
        "zip_code" : "75010",
        "city" : "Paris",
        "country" : "FRA"
    },
    "tag" : "account_type2"
}

RESPONSE

HTTP statusCase  
201
Success

Body-Property

Type

Value

Description

id

string

max size = 64

Account id

Response Sample
HTTP/1.1 201 CREATED
{
    "id": "AB-459652557845695458"
}


Get an account

Service to get account's information by id.

Account must belong to the requester Partner.

REQUEST

Operation:   GET /accounts/[id]

URL-Property

Type

Value

Description

id

string

max size = 64

Account id

Request Sample
GET /accounts/AS-459652557845695458

RESPONSE

HTTP statusCase
200
Success

Body-Property

Type

Description 

accountACCOUNT_INFO

Complete Account information

Sample - Standard
HTTP/1.1 200 OK
{
  "id" : "AS-459652557845695458",
  "type": "STANDARD",
  "status": "ACTIVE",
  "kyc_level": "LEVEL_1",
  "creation_date" : "2017-08-01T12:15:01+0100",
  "tag": "account_type1",
  "address": {
    "label1": "12 rue de Stalingrad",
    "city": "Puteaux",
    "country": "FRA",
    "zip_code": "92800"
  },
  "standard_info": {
    "subscriber" :{
      "lastname" : "Martin",
      "firstname" : "Philippe",
      "birthdate" : "1986-03-01",
      "nationality" : "FRA"
    },
    "email": "m.philippe@wha.fr"
  }
}
Sample - Business
HTTP/1.1 200 OK
{
  "id" : "AB-459652557845695459",
  "type" : "BUSINESS",
  "status" : "ACTIVE",
  "kyc_level" : "LEVEL_2",
  "creation_date" : "2017-09-01T09:15:01+0100",
  "tag" : "account_type2"
  "address" :{
    "label1" : "88 rue Barthe",
    "zip_code" : "75010",
    "city" : "Paris",
    "country" : "FRA"
  },
  "business_info": {
    "business_type" : "ASSOCIATION",
    "name":"Association Sportive P10",
    "registration_number" : "100018757",
    "phone_number" : "33129541388",
    "email" : "asw.contact@wha.fr",
    "representative" :{
      "lastname" : "Julien",
      "firstname" : "Dore",
      "birthdate" : "1970-12-01",
      "nationality" : "FRA"
    }
  }
}


Get account events

Service to get events for a specific account. Event can be a status change on account or his wallet, KYC level update, documents events...

List in order by event's date in descending order (last event is first the list).

REQUEST

Operation:   GET /accounts/[id]/events   ?per_page=[per_page]&page=[page]

URL-Property

Type

Value

Description   

id

string

max size = 64

Account id

per_page
 

integer

min = 1

max = 100

optional, default = 20

Number of events per page
page  integer

min = 1

optional, default = 1

Requested page number
Request Sample
GET /accounts/AS-459652557845695458/events

RESPONSE

HTTP statusCase
200
Success
Body-Property Type                        
Description
events

ACCOUNT_EVENT []

List of events

Object

ACCOUNT_EVENT

Property

Type                        

Value                                                       

Description                      

date

string

size = 16

Format:yyyy-MM-dd'T'HH:mm:ss'Z'

Event date

type

enum

  • ACCOUNT_CREATION
  • ACCOUNT_STATUS_UPDATE
  • ACCOUNT_DELETION
  • ACCOUNT_VALIDATION_SUBMITED
  • ACCOUNT_VALIDATION_VALIDATED
  • ACCOUNT_VALIDATION_INVALIDATED
  • ACCOUNT_VALIDATION_CANCELLED
  • DOCUMENT_CREATION
  • DOCUMENT_ADD_FILE
  • DOCUMENT_ARCHIVING
  • WALLET_CREATION
  • WALLET_STATUS_UPDATE
  • WALLET_DELETION
  • BANKACCOUNT_CREATION
  • BANKACCOUNT_STATUS_UPDATE
  • BANKACCOUNT_DELETION

Event type

message

string

max size = 300

optional

Event message (description/comment)

details

EVENT_DETAIL []

optional

Event's details. List of changed properties or any specific values related to the event.

Object

EVENT_DETAIL

Property

Type

Value

Description

key

string

max size = 100

Event detail key

value

string

max size = 200

Event detail value

old_value

string

max size = 200

optional

Optional old value associated to the key

Response Sample
HTTP/1.1 200 OK
[{
    "date": "2014-12-31T08:12:51+0100",
    "type": "WALLET_DELETION",
    "details": [{
        "key": "wallet_id",
        "value": "W-787841204695485624"
        },
        {
        "key": "status",
        "value": "DELETED",
        "old_value": "ACTIVE"}]
},
{
    "date": "2014-09-01T12:15:01+0100",
    "type": "WALLET_CREATION",
    "details": [{
        "key": "wallet_id",
        "value": "W-787841204695485624"}]
},
{
    "date": "2014-09-01T09:00:01+0100",
    "type": "ACCOUNT_CREATION"
}]


List of accounts

Service to get list of partner's accounts by type.

Results are ordered by descending creation date.

REQUEST

Operation:   GET /accounts   ?per_page=[per_page]&page=[page]&type=[type]

URL-Property

Type

Value                        

Description                                  

per_page

string

min = 1

max = 100

optional, default = 20

Number of accounts per page

pageinteger

min = 1

optional, default = 1

Requested page number

typeenum
  • STANDARD
  • BUSINESS

optional, default = all

Account type
Sample 1
GET /accounts?per_page=25&page=1&type=STANDARD
Sample 2
GET /accounts?type=BUSINESS
Sample 3
GET /accounts

RESPONSE

HTTP statusCase
200
Success
Body-Property  Type            
Description      
accounts

ACCOUNT []

List of accounts

Response Sample
HTTP/1.1 200 OK
 
[
  {
    "id" : "AS-459652557845695458",
    "type" : "STANDARD",
    "status" : "ACTIVE",
    "kyc_level" : "LEVEL_1",
    "creation_date" : "2014-09-01T12:15:01+0100"
    "tag" : "account_type1"
  },
  {
    "id" : "AB-459652557845695459",
    "type" : "BUSINESS",
    "status" : "ACTIVE",
    "kyc_level" : "LEVEL_2",
    "creation_date" : "2017-09-01T09:15:01+0100",
    "tag" : "account_type2"
  }
]


Update an account - Standard

Service to update standard account's informations. The optionnal and not required level properties can be modified or deleted. For delete any property value, set it to empty value.

REQUEST

Operation:   PUT /accounts/[id]/standard

Body-Property

Type

Value                          

Description                                 

subscriberSUBSCRIBERoptionalUser personal information
address

ADDRESS

optionalResidence address
email

string

max size = 128

optional (1)

Email

phone_numberstring

size = 12

digits only

international format (without 00 or + prefix)

optional (1)

Phone number

statusenum
  • ACTIVE
  • INACTIVE

optional

Account status
tagstring

max size = 100

optional

Field used by partner to set some customized information

(1): Email or Phone number is required.

Request Sample 1
PUT /accounts/AS-459652557845695458/standard
{
    "status" : "INACTIVE"
 }
Request Sample 1
PUT /accounts/AS-459652557845695458/standard
{
    "phone_number" : "33629878858"
 }



Request Sample 2
PUT /accounts/AS-459652557845695458/standard
{
    "subscriber" :{
        "lastname" : "Martin",
        "firstname" : "Philippe",
        "birthdate" : "1986-03-01"
    },
    "tag" : "account_type1"
}
Request Sample 3
PUT /accounts/AS-459652557845695458/standard
{
    "subscriber" :{
        "nationality" : "FRA"
    },
    "address" :{
        "label1" : "12 rue de Stalingrad",
        "zip_code" : "92800",
        "city" : "Puteaux",
        "country" : "FRA"
    }
}
Request Sample 4
PUT /accounts/AS-459652557845695458/standard
{
    "phone_number" : "",
    "subscriber" :{
        "nationality" : ""
    },
    "address" :{
        "label1" : "",
        "zip_code" : "92800",
        "city" : "Puteaux",
        "country" : "FRA"
    }
}

RESPONSE

HTTP statusCase
200
Success
Body
- None -
Response Sample
HTTP/1.1 200 OK


Update an account - Business

Service to update business account's informations. The optionnal and not required level properties can be modified or deleted. For delete any property value, set it to empty value.

REQUEST

Operation:   PUT /accounts/[id]/business

Body-Property

Type

Value                                                         

Description                                                                                    

namestring

max size = 64

optional

Organization name
business_typeenum
  • COMPANY
  • ASSOCIATION
  • SOLE_TRADER

optional

Type a business
email

string

max size = 128

optional

Organization email

phone_number

string

max size = 12

digits only

international format (without 00 or + prefix)

optional

Phone number

registration_numberstring

max size = 128

optional

SIRET for COMPANY or ASSOCIATION

License number for SOLE_TRADER

representative

REPRESENTATIVE

optionalRepresentative information
addressADDRESSoptionalOrganization address
statusenum
  • ACTIVE
  • INACTIVE
optional
Account status
tagstring

max size = 100

optional

Field used by partner to set some customized information

Delete an account

Service to delete an account.

Account deletion is only possible if all wallets balances are equals to zero.

REQUEST

Operation:   DELETE /accounts/[id]

URL-Property

Type

Value              

Description

id

string

max size = 64

Account id

Request Sample
DELETE /accounts/AS-459652557845695458

RESPONSE

HTTP statusCase 
204
Success
Body
- None -
Response Sample
HTTP/1.1 204 No Content


Common Objects

Object

ACCOUNT

Property

Type

Value                                                

Description   

id

string

max size = 64

Account id

typeenum
  • STANDARD
  • BUSINESS
  • PARTNER
Account type
statusenum
  • ACTIVE
  • INACTIVE
  • KYC_REQUIRED
  • SUSPENDED
Account status
kyc_levelenum
  • LEVEL_0
  • LEVEL_1
  • LEVEL_2
  • LEVEL_3
Account KYC level
creation_datestring

size = 64

Format:yyyy-MM-dd'T'HH:mm:ss'Z'

Account creation date


tagstringmax size = 100Field used by partner to set some customized information


Object

ACCOUNT_INFO

Property

Type

Value                                               

Description

id

string

max size = 64

Account id

typeenum
  • STANDARD
  • BUSINESS
  • PARTNER
Account type
statusenum
  • ACTIVE
  • INACTIVE (1)
  • KYC_REQUIRED (2)
  • SUSPENDED (3)
Account status
kyc_levelenum
  • LEVEL_0
  • LEVEL_1
  • LEVEL_2
  • LEVEL_3
Account KYC level
creation_datestring

size = 64

Format:yyyy-MM-dd'T'HH:mm:ss'Z'

Account creation date


tagstring

max size = 100

Field used by partner to set some customized information
address

ADDRESS


Account address

STANDARD
standard_info

STANDARD_INFO


Standard account information
BUSINESS
business_info

BUSINESS_INFO


Business account information

(1): INACTIVE account status blocks money flows (Transfer, Cash-in and Cash-out). All other operations are permitted.

(2): KYC_REQUIRED account status blocks account status update. Error message is returned when trying update status. It not blocks other fields update.

(3): SUSPENDED account status blocks money flows and delete account operations. It not blocks creation and update operations.


Object

STANDARD_INFO

Property

Type

Value

Description

phone_number

string

max size = 14

digits only

Phone number

email

string

max size = 120

Account email

subscriber

SUBSCRIBER


User personal information



Object

SUBSCRIBER

Property

Type

Value                              

Description

lastnamestring

max size = 64

Lastname
firstname

string

max size = 64

Firstname

birthdate

string

max size = 10

Format:YYYY-MM-DD

Birthdate

nationalitystring

size = 3

ISO 3166-1 code alpha-3

Nationality


Object

BUSINESS_INFO

Property

Type

Value                     

Description

name

string

max size = 64Organization name
registration_numberstring

max size = 128

Registration number.

SIRET for COMPANY or ASSOCIATION

License number for SOLE_TRADER

business_type

enum

  • COMPANY
  • ASSOCIATION
  • SOLE_TRADER
Business type
phone_number

string

max size = 14

digits only

Phone number

email

string

max size = 128

Email

representative

REPRESENTATIVE


Representative information


Object

REPRESENTATIVE

Property

Type

Value                             

Description

lastnamestringmax size = 64Representative lastname
firstname

string

max size = 64Representative firstname

birthdate

string

max size = 10

Format: YYYY-MM-DD

Representative birthdate


nationalitystring

size = 3

ISO 3166-1 code alpha-3

Representative nationality


Object

ADDRESS (1)

Property

Type

Value                                                               

Description

label1

string

max size = 64

Address label 1

label2

string

max size = 64

optional

Address label 2 (complementary information if required)

label3

string

max size = 64

optional

Address label 3 (complementary information if required)

zip_code

string

min size = 4

max size = 5

Zip Code

city

string

max size = 100

City

country

string

size = 3

Authorized country code ISO 3166-1 alpha-3 (2)

Country code

(1): deleting ADDRESS entity requires to set all ADDRESS's fields to empty value

(2): ISO 3166-1 code alpha-3 othe authorized countries :

GroupPaysCode











Eurozone countries

















AustriaAUT
BelgiumBEL
CyprusCYP
EstoniaEST
FinlandFIN
FranceFRA
GermanyDEU
GreeceGRC
IrelandIRL
ItaliaITA
LatviaLVA
LithuaniaLTU
LuxembourgLUX
MaltaMLT
NetherlandsNLD
PortugalPRT
SlovakiaSVK
SloveniaSVN
SpainESP





Other european union countries

BulgariaBGR
CroatiaHRV
Czech RepublicCZE
DenmarkDNK
HungaryHUN
PolandPOL
RomaniaROU
SwedenSWE
United KingdomGBR


Other european countries

IslandISL
LiechtensteinLIE
NorwayNOR

Accounts Documents Services

Create / Update Document(s)

Service to create or update document(s).

REQUEST

Operation:   PUT /accounts/[id]/documents

URL - Property

Type

Value

Description

id

string

max size = 64

 Account id

Body - Property

Type

Value

Description

documents

DOCUMENT []


 List of documents

Request Sample 1
PUT /accounts/AS-459652557845695458/documents
 
[{
  "type" : "PROOF_OF_ID",
  "files" : [{
    "file_name" : "identity_A.pdf",
    "content" : "....Base64...."
  },{
    "file_name" : "identity_B.pdf",
    "content" : "....Base64...."
  }]
},{
  "type" : "PROOF_OF_ADDRESS",
  "files" : [{
    "file_name" : "edf_2017.pdf",
    "content" : "....Base64...."
  }]
}]
Request Sample 2
PUT /accounts/AS-459652557845695459/documents
 
[{
  "type" : "PROOF_OF_ADDRESS",
  "mode" : "ADD",
  "files" : [{
    "file_name" : "phone_invoice.pdf",
    "content" : "....Base46...."
  }]
}]

RESPONSE

HTTP statusCase                                                                   

201

Success
Body
- None -
Response Sample
HTTP/1.1 201 CREATED


Get document

Service to get document

REQUEST

Operation:   GET /accounts/[id]/documents/[type]

URL - Property

Type

Value

Description          

id

string

max size = 64

 Account id

 typeenum

For STANDARD account:

  • PROOF_OF_ID
  • PROOF_OF_IBAN
  • PROOF_OF_ADDRESS

For BUSINESS account:

  • PROOF_OF_REGISTRATION
  • PROOF_OF_ID
  • PROOF_OF_IBAN
  • PROOF_OF_ADDRESS
 document type
Request Sample
GET /accounts/AS-459652557845695458/documents/PROOF_OF_ID

RESPONSE

HTTP statusCase                                                      
200
Success
Body-propertyTypeDescription
documentDOCUMENT
Full document information (with attached files)
Response Sample
HTTP/1.1 200 OK
 
{
  "type" : "PROOF_OF_ID",
  "status" : "CREATED",
  "tag" : "tag1",
  "files" : [{
    "file_name" : "identity_A.pdf",
    "content" : "....Base64...."
  },{
    "file_name" : "identity_B.pdf",
    "content" : "....Base64...."
  }]
}


List of documents

Service to get account's documents.

REQUEST

Operation:   GET /accounts/[id]/documents

URL - Property

Type

Value

Description                                                                

id

string

max size = 64

 Account id

Request Sample
GET /accounts/AS-459652557845695458/documents

RESPONSE

HTTP statusCase                                      
200
Success
Body-propertyTypeDescription
document

DOCUMENT [] 

List of documents (without files).
Response Sample
HTTP/1.1 200 OK
 
[{
  "type" : "PROOF_OF_ID",
  "status" : "VALID",
  "tag" : "tag1"
 },{
  "type" : "PROOF_OF_ADDRESS",
  "status" : "INVALID",
  "validation_error" : "UNREADABLE",
  "validation_desc" : "The document is unreadable"
}]


Delete document

Service to delete a account's document. Only document at CREATED or INVALID status could be deleted.

REQUEST

Operation:   DELETE /accounts/[id]/documents/[type]

URL - Property

Type

Value

Description

id

string

max size = 64

 Account id

Body - Property

Type

Value

Description

 typeenum

For STANDARD account:

  • PROOF_OF_ID
  • PROOF_OF_IBAN
  • PROOF_OF_ADDRESS

For BUSINESS account:

  • PROOF_OF_REGISTRATION
  • PROOF_OF_ID
  • PROOF_OF_IBAN
  • PROOF_OF_ADDRESS
 document type
Request Sample
DELETE /accounts/AS-459652557845695458/documents/PROOF_OF_ADDRESS

RESPONSE

HTTP statusCase                                                                   

204

Success
Body
- None -
Response Sample
HTTP/1.1 204 No Content



Common Objects

Object

DOCUMENT

Property

Type

Value

Description

 typeenum

For STANDARD account:

  • PROOF_OF_ID
  • PROOF_OF_IBAN
  • PROOF_OF_ADDRESS

For BUSINESS account:

  • PROOF_OF_REGISTRATION
  • PROOF_OF_ID
  • PROOF_OF_IBAN
  • PROOF_OF_ADDRESS
 Document type
tagstring

max size = 100

optional

Field used by partner to set some customized information
 filesFILE []


List of files
Request only
 modeenum
  • ADD
  • REPLACE

optional (default = REPLACE)

Add mode : sent files list will be added to the existing files list. If document not exist, it is created with sent files list.

Replace mode : files list will replace the existing list. It deletes existing document if exist

Response only
statusenum
  • CREATED
  • TO_VALIDATE
  • VALID
  • INVALID
Document status
creation_datestring

size = 16

Format:yyyy-MM-dd'T'HH:mm:ss'Z'

Creation Date
validation_errorenum
  • NOT_ACCEPTED
  • UNREADABLE
  • EXPIRED
  • NOT_COMPLIANT
  • OTHER
If status is INVALID, the cause of
validation_descString

max size = 300

Textual description of the validation error

Object

FILE

Property

Type

Value

Description

file_namestringmax size = 64File name
contentstring

max size = 2000000

Base 64 Format

File content in Base64 format.

Notice that the Base64 encoding of the file increases roughly of 30% the effective file size.

Example: A jpeg file of 150 ko converted to Base 64 will result in a string of 200 000 characters.

tagstring

max size = 100

optional

Field used by partner to set some customized information

Account KYC validation Services

Request KYC validation

Service to submit account to KYC validation.

The requested level must be greater than current level, if submition is accepted the account will be verified by backoffice (<48h). In the mean time, the account remains at the current level.

REQUEST

Operation:   PUT /accounts/[id]/validations/[kyc_level]/submit

URL-Property

Type

Value             

Description                      

id

string

max size = 64

Account id

kyc_levelenum
  • LEVEL_2
  • LEVEL_3
Target Account KYC level
Request Sample
PUT /accounts/AS-459652557845695458/validations/LEVEL_2/submit

RESPONSE

HTTP statusCase

200

Success
Body
- None -
Response Sample
HTTP/1.1 200 Ok


Get last KYC Validation status

Service to get the last KYC Validation request status for an account.

REQUEST

Operation:   GET /accounts/[id]/validations/last

URL-Property

Type

Value            

Description

id

string

max size = 64

Account id

Request Sample
GET /accounts/AS-459652557845695458/validations/last

RESPONSE

HTTP status
Case
200

Success

Body-Property

TypeValue

Description

kyc_levelenum
  • LEVEL_0
  • LEVEL_1
  • LEVEL_2
  • LEVEL_3
Account KYC level
statusenum
  • TO_VALIDATE
  • VALID
  • INVALID
Validation status
validation_errorenum
  • INCONSISTENT_DATA
  • INVALID_DOCUMENTS
  • OTHER

optional
If status is INVALID, the cause
validation_descString

max size = 300

optional

Textual description of the validation error
Sample - Standard
HTTP/1.1 200 OK
{
  "status": "VALID",
  "kyc_level": "LEVEL_1"
}
Sample - Standard
HTTP/1.1 200 OK
{
  "status": "INVALID",
  "kyc_level": "LEVEL_2",
  "validation_error":"OTHER",
  "validation_desc":"description ..."
 }


Get KYC Validations by Account

Service to get KYC Validations for a specified Account.

REQUEST

Operation:   GET /accounts/[id]/validations

URL-Property

Type

Value                       

Description                               

id

string

max size = 64

Account id

per_page

string

min = 1

max = 100

optional, default = 20

Number of accounts per page

pageinteger

min = 1

optional, default = 1

Requested page number

Request Sample
GET /accounts/AS-459652557845695458/validations/?per_page=10&page=1

RESPONSE

HTTP statusCase
200
Success
Body-Property         
Type                                
Description                               
account_validations

ACCOUNT_VALIDATION []

List of Validations of the Account

Sample - Standard
HTTP/1.1 200 OK
[
  {
    "account_id": "AS-459652557845695458",
    "status": "VALID",
    "kyc_level": "LEVEL_2",
    "date" : "2017-10-20T08:15:01+0100"
 },
  {
    "account_id": "AS-459652557845695458",
    "status": "INVALID",
    "kyc_level": "LEVEL_2",
    "validation_error":"OTHER",
    "validation_desc":"description ...",
    "date" : "2017-10-18T11:00:01+0100"
  },
  {
    "account_id": "AS-459652557845695458",
    "status": "VALID",
    "kyc_level": "LEVEL_1",
    "date" : "2017-10-01T09:15:01+0100"
  }
]

Get KYC Validations for all Accounts

Service to get KYC Validations for all Accounts.

REQUEST

Operation:   GET /accounts/validations

URL-Property

Type

Value                       

Description                               

id

string

max size = 64

Account id

per_page

string

min = 1

max = 100

optional, default = 20

Number of accounts per page

pageinteger

min = 1

optional, default = 1

Requested page number

Request Sample
GET /accounts/validations?per_page=5&page=1

RESPONSE

HTTP statusCase
200
Success
Body-Property         
Type                                
Description                               
account_validations

ACCOUNT_VALIDATION []

List of Account Validations

Sample - Standard
HTTP/1.1 200 OK
[
  {
    "account_id": "AS-986437287845690003",
    "status": "TO_VALIDATE",
    "kyc_level": "LEVEL_1",
    "date" : "2018-01-19T14:15:01+0100"
  },
  {
    "account_id": "AS-464382557845690001",
    "status": "VALID",
    "kyc_level": "LEVEL_2",
    "date" : "2017-10-18T10:55:01+0100"
  },
  {
    "account_id": "AS-464382557845690001",
    "status": "INVALID",
    "kyc_level": "LEVEL_2",
    "validation_error":"OTHER",
    "validation_desc":"description ...",
    "date" : "2017-10-17T14:30:01+0100"
  },
  {
    "account_id": "AS-164382597845690002",
    "status": "VALID",
    "kyc_level": "LEVEL_1",
    "date" : "2017-10-15T09:45:01+0100"
  },
  {
    "account_id": "AS-464382557845690001",
    "status": "VALID",
    "kyc_level": "LEVEL_1",
    "date" : "2017-10-14T10:15:01+0100"
  }
]


Common Objects

Object

ACCOUNT_VALIDATION



Property

Type

Value                                           

Description

account_id

string

max size = 64

Account id

kyc_levelenum
  • LEVEL_0
  • LEVEL_1
  • LEVEL_2
  • LEVEL_3
Account KYC level
statusenum
  • TO_VALIDATE
  • VALID
  • INVALID
Validation status
validation_errorenum
  • INCONSISTENT_DATA
  • INVALID_DOCUMENTS
  • OTHER

optional
If status is INVALID, the cause
validation_descString

max size = 300

optional

Textual description of the validation error
datestring

size = 64

Format:yyyy-MM-dd'T'HH:mm:ss'Z'

Validation submittion or modification date



Wallets services API

Services to create, get, update and delete wallets. A wallet is the container of the e-money unit.

The list of debit and credit operations done on a particular wallet could be obtained throw the wallet's activities.


Create a Wallet

Create a new Wallet for an account.

Multiple "EMONEY" wallets could be created per STANDARD or BUSINESS account.

Multiple "EMONEY" and "FEES" wallets could be created per partner account.

A "FEES" wallet is a wallet that can be used by the partner to collect fees during any transactions (transfer, cash-in, cash-out).

REQUEST

Operation:   POST /wallets

Body - Property

Type

Value

Description

account_id 

string

max size = 64

optional, default = the partner account id

Account id

type

enum

In case of a STANDARD or BUSINESS account :

  • EMONEY

In case of a PARTNER account :

  • EMONEY
  • FEES

optional, default = EMONEY

Wallet type

currency

string


max size = 3

optional, default = the currency of the partner is used.

ISO 4217 currency code

tagstring

max size = 100

optional

Custom metadata
Sample - Request
POST /wallets
{
    "account_id" : "A-459652557845695458",
    "type" : "EMONEY"
}

RESPONSE

HTTP statusCase
201
Success

Body - Property

Type

Value

Description                                                                

id

string

max size = 64

Wallet id

Sample - Response
HTTP/1.1 201 CREATED
{
    "id" : "WE-787841204695485624"
}


Update a Wallet

Update wallet's tag or status.

REQUEST

Operation:   PUT /wallets/[id]

URL - Property

Type

Value

Description                                                                

id

string

max size = 64

Wallet id

Body - Property

Type

Value

Description                                                                

tagstring

max size = 100

optional

Custom metadata
status

enum

  • ACTIVE
  • INACTIVE

optional

Wallet status
Sample - Request
PUT /wallets/WE-787841204695485624
{
    "tag" : "new_tag"
}

RESPONSE

HTTP statusCase
200
Success
Body
- None -
Sample - Response
HTTP/1.1 200 OK


Delete a Wallet

Delete a wallet.

This operation is possible only if the balance is equal to zero. Money should transfer to another wallet or cash-out.

REQUEST

Operation:   DELETE /wallets/[id]

URL - Property

Type

Value

Description                                                                

id

string

max size = 64

Wallet id

Sample - Request
DELETE /wallets/WE-787841204695485624

RESPONSE

HTTP statusCase
204
Success
Body
- None -
Sample - Response
HTTP/1.1 204 OK


Get a Wallet

Retrieve data of a single wallet.

REQUEST

Operation:   GET /wallets/[id]

URL - Property

Type

Value

Description                                                                

id

string

max size = 64

Wallet id

Sample - Request
GET /wallets/WE-787841204695485624

RESPONSE

HTTP statusCase
200
Success
Body - Property Type
Description                                                                
-WALLETWallet data
Sample - Response
HTTP/1.1 200 OK
{
    "id" : "WE-787841204695485624",
    "account_id" : "A-459652557845695458",
    "tag" : "My wallet",
    "status" : "ACTIVE",
    "type" : "EMONEY",
    "creation_date" : "2017-06-30T10:35:20+0100",
    "balance" : 1000,
    "balance_available" : 900,
    "currency" : "EUR"
 }


List Wallets

List Wallets for the given optionnal criteria.

Sorted by creation date DESC.

REQUEST

Operation:   GET /wallets   ?account_type=[account_type]&account_id=[account_id]&per_page=[per_page]&page=[page]

URL - Property

Type

Value

Description                                                                

account_type

enum

  • STANDARD
  • BUSINESS
  • PARTNER

optional, default = all

Type of account(s) associated to the wallets.

account_id

string

max size = 64

optional

Id of the account associated to the wallets.

If this parameter is given, the "account_type" filter is ignored.

per_page

integer

min = 1

max = 100

optional, default = 20

Number of wallets per page

page

integer

min = 1

optional, default = 1

Requested page number

Sample - Request
GET /wallets?account_type=STANDARD&account_id=AS-459652557845695458&per_page=5&page=1

RESPONSE

HTTP statusCase
200
Success
Header - PropertyTypeDescription                                  
x-pageintegerIndex of the page
x-page-sizeintegerCapacity of the page
x-total-elementslongThe overall amount of elements
x-total-pagesintegerThe number of pages

Body - Property

Type

Description                                  

-

WALLET []

List of wallets

Sample - Response
HTTP/1.1 200 OK
{
    {
        "id" : "WE-587456225465456545",
        "account_id" : "AS-459652557845695458",
        "tag" : "My first wallet",
        "status" : "ACTIVE",
        "type" : "EMONEY",
        "creation_date" : "2017-06-30T10:35:20+0100",
        "balance" : 1000,
        "balance_available" : 900,
        "currency" : "EUR"
    },       
    {
        "id" : "WE-998459651236647987",
        "account_id" : "AS-459652557845695458",
        "tag" : "My second wallet",
        "status" : "ACTIVE",
        "type" : "EMONEY",
        "creation_date" : "2017-07-01T10:35:20+0100",
        "balance" : 500.5,
        "balance_available" : 500.5,
        "currency" : "EUR"
    }
}


List Wallet Activities

List activities of a given wallet (sorted by date).

An activity represents any DEBIT or CREDIT operation performed on a wallet.

Each activity could be related to a transaction (transfer, cash-in, cash-out).

REQUEST

Operation:   GET /wallets/[wallet_id]/activities   ?per_page=[per_page]&page=[page]&type=[type]

URL - Property

Type

Value

Description                                                                

wallet_id

string

max size = 64

Wallet id

per_page

integer

min = 1

max = 100

optional, defaut = 20

Number of activities by page

page

integer


min = 1

optional, defaut = 1

Page number

type

enum

  • CREDIT
  • DEBIT

optional, default = All

Activity type

Request Sample
GET /wallets/WE-123154689541127/activities?per_page=10&page=1&type=CREDIT

RESPONSE

HTTP statusCase
200
Success
Header - PropertyTypeDescription                                  
x-pageintegerIndex of the page
x-pageSizeintegerCapacity of the page
x-totalElementslongThe overall amount of elements
x-totalPagesintegerThe number of pages
Body - PropertyTypeDescription

-

WALLET_ACTIVITY []

List of wallet activities

Response Sample
HTTP/1.1 200 OK
{
    {
        "id" : "o-045267"
        "wallet_id" : "WE-123121512466869",
        "trx_id" : "TX-0452670124112789",
        "date" : "2017-06-30T11:25:40+0100",
        "type" : "CREDIT",
        "amount" : 10",
        "balance_after" : 100
    },
    {
        "id" : "o-045280"
        "wallet_id" : "WE-123121512466869",
        "trx_id" : "TX-0452670124112789",
        "date" : "2017-07-01T08:15:55+0100",
        "type" : "CREDIT",
        "amount" : 50.1,
        "balance_after" : 150.35
    },
    {
        "id" : "o-045299"
        "wallet_id" : "WE-1232154254541521",
        "trx_id" : "TX-04529921124154521",
        "date" : "2017-07-02T09:40:15+0100",
        "type" : "DEBIT",
        "amount" : 80,
        "balance_after" : 70
    }
}


Get a Wallet Activity

Get information about a single wallet activity.

REQUEST

Operation:   GET /wallets/[wallet_id]/activities/[id]

URL - Property

Type

Value

Description                                                                

wallet_id

string

max size = 64

Wallet id

idstringmax size = 64Activity id
Request Sample
GET /wallets/WE-1232154254541521/activities/o-045267

RESPONSE

HTTP statusCase
200
Success

Body - Property

TypeDescription
-WALLET_ACTIVITYActivity data
Response Sample
HTTP/1.1 200 OK
{
    "id" : "o-045267"
    "wallet_id" : "WE-1232154254541521",
    "trx_id" : "TX-0452672415241252",
    "date" : "2017-06-30T11:25:40+0100",
    "type" : "CREDIT",
    "amount" : 100,
    "balance_after" : 100
}




Common Objects

 

Object

WALLET

Property

Type

Value

Description                                                            

idstringmax size = 64Wallet id
account_idstringmax size = 64Account id
tagstringmax size = 100Custom metadata

status

enum

  • ACTIVE
  • INACTIVE
Wallet status
type

enum

In case of a STANDARD or BUSINESS account :

    • EMONEY

In case of a PARTNER account :

    • EMONEY
    • FEES

Wallet type

creation_datestring

size = 24

Format: yyyy-MM-dd'T'HH:mm:ss'Z'

Wallet creation date


balancedouble
Balance in the wallet's currency
balance_availabledoubleMay be less than the balance if two-step trx are in progress

Available balance

currency

string

size = 3

ISO 4217 currency code

Currency code


Object

WALLET_ACTIVITY

Property

Type

Value

Description                                                            

idstringmax size = 64Activity id
wallet_idstringmax size = 64Wallet id
trx_idstringmax size = 64Transaction id related to the activity
datestring

size = 24

Format: yyyy-MM-dd'T'HH:mm:ss'Z'

Activity Date

type

enum

  • CREDIT
  • DEBIT

Type

amountdouble
Amount in the wallet's currency
balance_afterdouble

Balance of the wallet after the activity.

It permits to have an history of the balance changes over time.


Transactions services

Get a transaction

REQUEST

Operation:   GET /transactions/[id]

URL - Property

Type

Value

Description 

id

string

max size = 64

Transaction id

Request Sample
GET /transactions/TX-8148254337416765

RESPONSE

HTTP statusCase
200
Success

Body - Property

Type

Description

-

TRANSACTION

Transaction details

Response Sample - TRANSFER
HTTP/1.1 200 OK
{  
    "id" : "TX-198285437246552",
    "status" : "CONFIRMED",
    "type" : "TRANSFER",
    "tag": "transfer_1",
    "creation_date" : "2017-07-01T11:20:44+0100",
    "execution_date" : "2017-07-01T22:00:00+0100",
    "authorization_date" : "2017-07-01T11:21:04+0100",
    "partner_ref" : "REF-TSF-u1568-20170701112043",
    "sender_wallet_id" : "WE-1945224421212179",
    "receiver_wallet_id" : "WE-1756418894132751",
    "fees_wallet_id" : "WF-1010213278996452",
    "amount" : 200,
    "fees" : 10,
    "payment_method" : "TRANSFER"
 }
Response Sample - CASH-OUT
{
   "id": "TX-7303042667838514",
   "status": "CONFIRMED",
   "type": "CASH_OUT",
   "tag": "cashout_1",
   "amount": 2,
   "fees": 1.5,
   "payment_method": "BANK_TRANSFER",
   "creation_date": "2017-12-14T14:52:41+0100",
   "authorization_date": "2017-12-14T14:52:41+0100",
   "authorization_timeout_date": "2018-01-13T14:52:41+0100",
   "execution_date": "2017-12-14T14:52:41+0100",
   "partner_ref": "REF-CO-15132595614775958",
   "sender_wallet_id": "WE-6158333978932868",
   "fees_wallet_id": "WF-8671520527517770",
   "bank_account": {
      "id": "BA-2571587768817089",
      "number": "FI135XXXXXXXX00056",
      "bic": "BNPAFRPP"
   }
}
Response Sample - CASH-IN - REFUNDED
{
   "id": "TX-4854126479854849",
   "refund_trx_id": "TX-6621452595900437",
   "status": "REFUNDED",
   "type": "CASH_IN",
   "amount": 20,
   "payment_method": "CREDIT_CARD",
   "creation_date" : "2017-07-01T11:20:44+0100",
   "authorization_date" : "2017-07-01T11:21:04+0100",
   "authorization_timeout_date": "2017-01-14T11:21:05+0100",
   "execution_date" : "2017-07-01T22:00:00+0100",
   "partner_ref": "REF-CI-464646464649847",
   "receiver_wallet_id": "WE-6158333978932868",
   "credit_card": {
      "id": "CC-45787895415325478",
      "number": "4000XXXXXXXXXXXX0002",
      "brand": "VISA",
      "expiry_date": "10/2019"
   }
}
Response Sample - REFUND Transaction
{
   "id": "TX-6621452595900437",
   "intial_trx_id" : "TX-4854126479854849",
   "status": "CONFIRMED",
   "type": "CASH_IN",
   "execution_date": "2017-09-15T14:12:41+0100"
}

REFUND Transaction

For REFUND transaction, the service returns only id, intial_trx_id, status, type, execution_date


Get a Transaction from partner transaction reference

Get a transaction's detail from partner transaction reference that system provides at transaction initiation.

N.B : Useful to retrieve transaction status in case of timeout.

REQUEST

Operation:   GET /transactions/partner_ref/[partner_ref]

URL - Property

Type

Value

Description

partner_ref

string

max size = 64

Partner transaction reference.

N.B : This reference is choose and given by the partner at the creation of a transaction. It's not the transaction id.

Request Sample
GET /transactions/partner_ref/REF-TSF-u1568-20170713164517

RESPONSE

HTTP statusCase
200
Success

Body - Property

Type

Description     

-

TRANSACTION

Transaction details

Response Sample - CASH-IN
HTTP/1.1 200 OK
{  
    "id" : "TX-198285437246552",
    "status" : "AUTHORIZED",
    "type" : "CASH_IN",
    "tag": "cashin_1",
    "creation_date" : "2017-07-13T16:45:17+0100",
    "authorization_date" : "2017-07-13T16:46:25+0100",
    "auth_timeout_date" : "2017-07-14T05:00:00+0100",
    "partner_ref" : "REF-TSF-u1568-20170713164517",
    "receiver_wallet_id" : "WE-1756418894132751",
    "fees_wallet_id" : "WF-1010213278996452",
    "amount" : 100,
    "fees" : 5,
    "payment_method" : "CREDIT_CARD"
    "credit_card" : {
        "id" : "CC-4596412577814814",
        "number" : "4002XXXXXXXX1458",
        "expiry_date" : "12/2021",
        "brand" : "VISA"
    }
 }

List Transactions

REQUEST

Operation:   GET /transactions   ?per_page=[per_page]&page=[page]&type=[type]&wallet_id=[wallet_id]

URL - Property

Type

Value

Description                                                                

per_pagestring

min = 1

max = 100

optional, default = 20

Number of transactions per page

page

string

min = 1

optional, default = 1

Requested page number

typeenum
  • TRANSFER
  • CASH_IN
  • CASH_OUT

optional, default = All

Transaction type

wallet_idstring

size max = 64

optional

Wallet id (Sender, Receiver or Fees Wallet)
Request Sample
GET /transactions?per_page=5&page=1&type=TRANSFER
  • This service does not return REFUND transactions in the list.
  • REFUND transaction details are returned by the GET transaction service (using the refund_trx_id optained on the refunded transaction).

RESPONSE

Format :

HTTP statusCase
200
Success

Body - Property

Type

Description

-

TRANSACTION []

List of transactions

Response Sample
HTTP/1.1 200 OK
[
    {  
        "id" : "TX-198285437246552",
        "status" : "CONFIRMED",
        "type" : "CASH_IN",
        "tag": "cashin_1",
        "creation_date" : "2017-07-04T16:45:17+0100",
        "execution_date" : "2017-07-04T22:01:18+0100",
        "authorization_date" : "2017-07-04T16:46:25+0100",
        "partner_ref" : "REF-CI-u1568-20170704164517",
        "receiver_wallet_id" : "WE-345952557845695458",
        "fees_wallet_id" : "WF-123456789123456789",
        "amount" : 105,
        "fees" : 5,
        "payment_method" : "CREDIT_CARD"
    },
    {  
        "id" : "TX-8148254337416765",
        "status" : "CONFIRMED",
        "type" : "TRANSFER",
        "tag": "transfer_1",
        "creation_date" : "2017-07-05T11:20:44+0100",
        "execution_date" : "2017-07-05T22:02:01+0100",
        "authorization_date" : "2017-05-01T11:21:04+0100",
        "partner_ref" : "REF-TSF-u2114-20170501112043",
        "sender_wallet_id" : "WE-4596525578456954",
        "receiver_wallet_id" : "WE-9876543219876543",
        "amount" : 210,
        "payment_method" : "TRANSFER"
    },
    {
        "id": "TX-6621452595900437",
        "refund_trx_id": "TX-0931242561570980",
        "status": "REFUNDED",
        "type": "TRANSFER",
        "tag": "transfer_2",
        "amount": 210,
        "fees": 5,
        "creation_date": "2017-07-06T19:00:19+0200",
        "authorization_date": "2017-07-06T19:00:19+0200",
        "authorization_timeout_date": "2017-08-05T19:00:19+0200",
        "execution_date": "2017-07-06T19:00:19+0200",
        "partner_ref": "REF-TSF-u2114-201012468043",
        "sender_wallet_id" : "WE-4596525578456954",
        "receiver_wallet_id": "WE-9876543219876543",
        "fees_wallet_id": "WF-1234567891234567",
        "payment_method": "TRANSFER"
    }
 
 ]


Refund a Transaction (Transfer, Cash-in)

Refund a CONFIRMED transaction. Only TRANSFER and CASH_IN transactions could be refunded.

REQUEST

Operation:   PUT /transaction/[id]/refund

URL - Property

Type

Value

Description

id

string

max size = 64

Transaction id

Body
- None -
Request Sample
PUT /transactions/TX-8148254337416765/refund

RESPONSE

As result, the id of the refund transaction generated is returned. The status of the refunded transaction is updated to REFUNDED.

HTTP status
Case

200


Success

Body - property


Type

Description

idstringmax size = 64Refund transaction id

If transaction failed, HTTP code is different of 400 and an error structure is in the body.

Response Sample - Transfer -
HTTP/1.1 200 OK
{
    "id": "TX-0148255537412144"
 }



Common Objects

 

Object

TRANSACTION

Property

Type

Value

Description

idstringmax size = 64Transaction id
refund_trx_idstring

max size = 64

Refund transaction id.

Only for refunded transaction (transaction at REFUNDED status)

initial_trx_idstring

max size = 64

Initial transaction id.

Only for a refund transaction (transaction generated by a refund).

statusenum
  • INITIATED
  • AUTHORIZED
  • CANCELED
  • CONFIRMED
  • FAILED
  • REFUNDED

Transaction status

typeenum
  • TRANSFER
  • CASH_IN
  • CASH_OUT

Transaction type

tagstringmax size = 100Custom metadata
payment_methodenum
  • TRANSFER
  • CREDIT_CARD
  • BANK_TRANSFER
Payment method
creation_datestring

size = 24

Format : yyyy-MM-dd'T'HH:mm:ss'Z'

Transaction creation date.

authorization_datestring

size = 24

Format : yyyy-MM-dd'T'HH:mm:ss'Z'

Transaction authorization date.

authorization_timeout_datestring

size = 24

Format : yyyy-MM-dd'T'HH:mm:ss'Z'

Maximal date to confirm an AUTHORIZED transaction.

execution_datestring

size = 24

Format : yyyy-MM-dd'T'HH:mm:ss'Z'

Cancel or confirmation date.

partner_refstring

max size = 64

Partner unique internal reference
sender_wallet_idstring

max size = 64

only for TRANSFER or CASH_OUT

Id of the sender wallet.


receiver_wallet_idstring

max size = 64

only for TRANSFER or CASH_IN

Id of the receiver wallet.


fees_wallet_idstring

max size = 64

optional

Id of the wallet where the "fees" are credited.
amountdouble
Amount of the transfer
feesdoubleoptionalFees amount taken by the partner
currency

string

size = 3

ISO 4217 currency code

Currency code

bank_accountBANK_ACCOUNT_INFO

only if "payment_method" is BANK_TRANSFER

not returned when request the list of transactions

Summary of bank account data
credit_cardCREDIT_CARD_INFO

only if "payment_method" is CREDIT_CARD

not returned when request the list of transactions

Summary of credit card data


Object

BANK_ACCOUNT_INFO

Property

Type

Value

Description

idstringmax size = 64Bank account id
numberstringmax size = 34

IBAN (International Bank Account Number).

The IBAN consists of the country code, two check digits and the account number.

bic

string

max size = 12

optional

The BIC (Business Identifier Code, SWIFT code) that identifies the bank or bank group.


Object

CREDIT_CARD_INFO

Property

Type

Value

Description

idstringmax size = 64Credit card id
numberstring

size = 16

digits only

Credit card number

Only digits from 1 to 4 and 12 to 16 are visible, others are replaced with an 'X'.

Exemple: "4002XXXXXXXX4587"

expiry_datestring

size = 7

Format: MM/YYYY

Credit card expiry date

brandstring
  • VISA
  • MASTERCARD
  • CB

Credit card type

Transfer P2P services

Services to create, update and delete transfers P2P.

A P2P (Point-to-Point or Peer-to-Peer) transfer is a transfer of e-money between two "EMONEY" wallets.

Optionnaly, some fees can be collected by the partner during the operation.


Execute a single-step Transfer

Execute a new transfer in one step.

REQUEST

Operation:   POST /transfers

Body - Property

Type

Value

Description

partner_ref

string

max size = 64

Partner unqiue internal reference of the transaction.

N.B : This reference is useful to retrieve transaction status in case of timeout, using :

GET /transactions/partner_ref/{partner_ref}

tagstring

max size = 100

optional

Custom metadata
sender_wallet_idstringmax size = 64Id of the wallet where the amount is debited
receiver_wallet_idstringmax size = 64Id of the wallet where the amount - fees is credited
fees_wallet_idstring

max size = 64

optional

Id of the wallet where the fees are credited.

If not set, no fees will be charged to the sender.

This wallet should be associated to the partner's account.

amountdoublemin = 0.01

Amount of the transfer (fees included).

The sender wallet is debited of the amount.

The receiver wallet is credited of the amount-fees.

feesdoubleoptional, default = 0

Fees amount taken by the partner.

Take into account only if a fees_wallet_id is defined.

Request Sample
POST /transfers
{
    "partner_ref" : "TSF-u1594-20180310093048",
    "tag" : "Chuck Birthday gift",
    "sender_wallet_id" : "WE-4596525578456954",
    "receiver_wallet_id" : "WE-9876543219876543",
    "fees_wallet_id" : "WF-1234567891234567",
    "amount" : 210,
    "fees" : 3
}

RESPONSE

HTTP statusCase
201
Success

Body - property

Type

Value

Description  

id

string

max size = 64

Transaction id

If transaction failed, HTTP code is different of 400 and an error structure is in the body.

Response Sample
HTTP/1.1 201 CREATED
{
    "id" : "TX-8148254337416765"
}


Create a Transfer Authorization

Create a new transfer authorization.

The amount are reserved on the sender wallet until a delay defined by partner. This amount is not anymore available for other transaction until the transaction is cancelled or the delay is passed.

REQUEST

Operation:   POST /transfers/authorize

Body - Property

Type

Value

Description

Same parameters as the 1-step transfer request, plus the parameters below:

auth_timeout_delay

integer

maximum = 2592000 (30 days)

optional, default = maximum

Reservation delay in seconds of the transaction amount

Request Sample
POST /transfers/authorize
{
    "partner_ref" : "TSF-u1594-2018-03-09-193048",
    "tag" : "Chuck Birthday gift",
    "sender_wallet_id" : "WE-4596525578456954",
    "receiver_wallet_id" : "WE-9876543219876543",
    "fees_wallet_id" : "WF-1234567891234567",
    "amount" : 210,
    "fees" : 5,
    "auth_timeout_delay" : 86400
}

RESPONSE

HTTP statusCase

201

Success

Body - Property

Type

Value

Description

idstring

max size = 64

Transaction id

Response Sample
HTTP/1.1 201 CREATED
{
    "id" : "TX-8148254337416765"
 }

Cancel a Transfer Authorization

Cancel an AUTHORIZED transfer.

REQUEST

Operation:   DELETE /transfers/[id]

URL - Property

Type

Value

Description 

id

string

max size = 64

Transaction id

Request Sample
DELETE /transfers/TX-8148254337416765

RESPONSE

HTTP statusCase
204
Success
Body
- None -
Response Sample
HTTP/1.1 204 OK


Confirm a Transfer Authorization

Confirm an AUTHORIZED transfer.

REQUEST

Operation:   PUT /transfers/[id]

URL - Property

Type

Value

Description

id

string

max size = 64

Transaction id

Body
- None -
Request Sample
PUT /transfers/TX-8148254337416765

RESPONSE

HTTP statusCase
200
Success
Body
- None -
Response Sample
HTTP/1.1 200 OK

Cash-in services

Initiate a cash-in (via Credit Card Payment Form)

Initiate a new cash-in transaction by credit card via a Web Payment Panel.

As response, the service provides:

    • redirect_url giving the default Web Payment Panel address (hosted by W-HA) where the user should be redirect to proceed to payment (or throught an iframe included in the partner web site)
    • alternatively, payment_url and payment_token to be used with a customized Payment Panel (see Panel Customization Part for details).

Once the payment is done (successfuly or not), user is redirected to the return_url provides in the request. The id (W-HA reference) of the transaction is added as a query parameter to the provided URL.

Partner should request transaction status to the API to have the final status of the payment: AUTHORIZED or FAILED.

If AUTHORIZED, the partner should finally confirmed the cash-in within the authorization delay. The money is then credited to the receiver wallet (and fees wallet if defined).

Accepted Credit Card are VISA, MASTERCARD and CB (Carte Bleue).

Payment with 3DSecure process is mandatory.

Notice that, in the payment panel web form, the user can choose to save his credit card for further payment. If so, the credit card will be associated to the payer_account_id and could be reused to perform direct credit card payment throught the API (see next part).


REQUEST

Operation:   POST /cash-in/creditcards/init

Body - Property

Type

Value                     

Description                                                                

partner_ref

string

max size = 64

Partner unique internal reference of the transaction.

N.B : This reference is useful to retrieve transaction status in case of timeout, using :

GET /transactions/partner_ref/{partner_ref}

tagstring

max size = 100

optional

Custom metadata
payer_account_idstring

max size = 64

optional

Account Id of the payer initiating the cash-in (owner of the payment mean).

If not specified, it is equal to the owner of the receiver_wallet.

receiver_wallet_idstringmax size = 64Id of the EMONEY wallet where the money is credited (STANDARD or BUSINESS account)
fees_wallet_id

string

max size = 64

optional

Id of the FEES wallet where the fees are credited
amountdoublemin = 0.01

Amount of the cash-in (fees included).

The user is charged of the amount on his payment mean (e.g. credit card) but is credited of the amount-fees on his wallet.

feesdoubleoptional, default = 0

Fees amount taken by the partner

auth_timeout_delay

integer




maximum = 604800 (7 days)

optional, default = maximum

Reservation delay in seconds of the transaction amount
return_urlstring max size = 200Partner redirect URL when the payment is has been processed by the end-user.
lang

string

language ISO code :

  • en
  • fr

size = 2

optional, defaut = en

Language ISO code of the payment panel :

  • en → english
  • fr → french
descriptionstringmax size = 14Customized cash-in transaction description
Sample - Request
POST /cash-in/creditcards/init
{
    "partner_ref" : "REF-CO-A164684461621621",
    "tag" : "My cash-out",
    "receiver_wallet_id" : "WE-9876543219876543",
    "fees_wallet_id" : "WF-1234567891234567",
    "amount" : 105,
    "fees" : 5,
    "return_url" : "https://www.mysite.com/store/cash-in",
    "lang" : "fr",
    "auth_timeout_delay" : 86400
}

RESPONSE

HTTP status         
Case
201
Success

Body - Property

Type

Value              

Description                                                                

idstringmax size = 64Cash-out transaction id
redirect_urlstringmax size = 300URL of the payment panel where the partner should redirect the user to perform payment authorization.
payment_urlstring
The URL of the payment service to include the payment panel (see Credit Card Payment Panel)
payment_tokenstringmax size = 300A token to provide to the payment service to include the payment panel (see Credit Card Payment Panel)
Sample - Request
HTTP/1.1 201 CREATED
{
    "id" : "TX-8148254337416765",
}


Execute a single-step cash-in (via a registered Credit Card)

Execute a new cash-in transaction with an already registered credit card in a single call (no need to confirm).

REQUEST

Operation:   POST /cash-in/creditcards/[id]

URL - Property

Type

Value                     

Description                                                                

idstring

max size = 64

Id of the credit card used for the payment.

Body - Property

Type

Value

Description                                                                

partner_ref

string

max size = 64

Partner unique internal reference of the transaction.

N.B : This reference is useful to retrieve transaction status in case of timeout, using :

GET /transactions/partner_ref/{partner_ref}

tagstring

max size = 100

optional

Custom metadata
receiver_wallet_idstringmax size = 64Id of the EMONEY wallet where the amount is credited (STANDARD or BUSINESS account)
fees_wallet_id

string

max size = 64

optional

Id of the FEES wallet where the fees are credited
amountdouble
Amount of the cash-in
feesdoubleoptional, default = 0Fees amount taken by the partner. The user is charged of amount on his payment mean (credit card) but is credited of the amount-fees on his wallet.
descriptionstringmax size = 14Customized cash-in transaction description
Sample - Request
POST /cash-in/creditcards/CC-1465716476464676
{
    "partner_ref" : "REF-CO-A164684461621621",
    "payment_method" : "CREDIT_CARD",
    "receiver_wallet_id" : "WE-9876543219876543",
    "receiver_wallet_id" : "WE-9876543219876543",
    "fees_wallet_id" : "WF-1234567891234567",
    "amount" : 105,
    "fees" : 5
}

RESPONSE

HTTP status         
Case
201
Success

Body - Property

Type

Value           

Description                                                                

idstringmax size = 64Cash-out transaction id

The transaction is at "CONFIRMED" status. The money is provisionned to the receiver wallet.

Sample - Request
HTTP/1.1 201 CREATED
{
    "id" : "TX-8148254337416765"
}


Create a cash-in Autorization (via a registered Credit Card)

Initiate a new cash-in transaction with an already registered credit card.

REQUEST

Operation:   POST /cash-in/creditcards/[id]/authorize

URL - Property

Type

Value                                  

Description                                                                

idstring

max size = 64

Id of the credit card used for the payment.

Body - Property

Type

Value

Description                                                                

Same parameters as the single-step cash-in request, plus the parameters below:
auth_timeout_delay

integer




maximum = 604800 (7 days)

optional, default = maximum

Reservation delay in seconds of the transaction amount.
Sample - Request
POST /cash-in/creditcards/CC-1465716476464676/authorize
{
    "partner_ref" : "REF-CO-A164684461621621",
    "payment_method" : "CREDIT_CARD",
    "receiver_wallet_id" : "WE-9876543219876543",
    "receiver_wallet_id" : "WE-9876543219876543",
    "fees_wallet_id" : "WF-1234567891234567",
    "amount" : 105,
    "fees" : 5,
    "auth_timeout_delay" : 86400
}

RESPONSE

HTTP status         
Case
201
Success

Body - Property

Type

Value           

Description                                                                

idstringmax size = 64Cash-out transaction id

The transaction is at "AUTHORIZED" status. The money is provisionned to the receiver wallet only after transaction confirmation.

Sample - Request
HTTP/1.1 201 CREATED
{
    "id" : "TX-8148254337416765"
}


Cancel an Authorized cash-in

Cancel a INITIATED or AUTHORIZED cash-in transaction.

REQUEST

Operation:   DELETE /cash-in/[id]

URL-Property

Type

Value            

Description

id

string

max size = 64

Transaction id

N.B : This id was previously returned upon a call to POST /cash-in

Sample - Request
DELETE /cash-in/TX-8148254337416765

RESPONSE

HTTP statusCase                                                  
204
Success
Body
- None -
Sample - Response
HTTP/1.1 204 OK


Confirm an Authorized cash-in

Confirm an AUTHORIZED cash-in transaction.

The receiver and fees wallets are credited at this moment.

REQUEST

Operation:   PUT /cash-in/[id]

URL-Property

Type

Value            

Description

id

string

max size = 64

Transaction id

N.B : This id was previously returned upon a call to POST /cash-in

Sample - Request
PUT /cash-in/TX-8148254337416765

RESPONSE

HTTP statusCase                                                  
200
Success
Body
- None -
Sample - Request
HTTP/1.1 200 OK

Credit Card Payment Panel Customization

This page explains how to customized the Credit Card Payment Panel used for the CASH-IN.

The customization is based on the integration of a specific template in partner HTML page and by using a provided Javascript Library. As a result, it injects the frame of a payment panel hosted by API-money server (PCI-DSS compliant) directly into the partner Web page.

It permits to :

    • choose the position/size of the different inputs
    • change the style of the inputs and errors by CSS
    • customize the different text labels
    • customize the different error messages

Image 1 : Default credit card payment form panel


Image 2 : Default credit card payment form panel with the error messages


By default, the payment form is in English but language could be defined during CASH_IN initiation through the "lang" parameter. So far, "en" and "fr" are supported.


How to include a Payment Panel (minimal inclusion)

<html>
    <head>
        ...
        <!-- JS library import -->
        ...
    </head>
    <body>
        ...
        <!-- Payment panel tag -->
        <div id="paymentForm">
        </div>
        ...
        <script>
            ...
            var paymentURL = 'https://secure-cb.w-ha.com/secure-node-ems/purchase-form'; <!-- this value should be obtained from CASH_IN initiation response -->
            var paymentToken = '654fsd4fs6d4fsd64fs6d4fs6d4fs6dfsdfsdf54f'; <!-- this value should be obtained from CASH_IN initiation response -->
            var styleCSSCustom = {};
 
            <!-- JS function call : Iframe injection -->
            SecureCb.injectIframe('paymentForm', paymentURL, paymentToken, styleCSSCustom);
        </script>
    </body>
</html>


Step 1 : Import JS library

First the Javascript library secure-cb.min.js has to be imported into the HTML page.

Library URL :

<html>
    <head>
        ...
        <!-- JS library import -->
        ...
    </head>
    <body>
        ...
    </body>
</html>


Step 2 : HTML static part

Put a <div> tag with a specific ID into the HTML body. This ID has to be re-used at the step 4.

This div will be replaced by the payment panel form.

<html>
    <head>
        ...
        <!-- JS library import -->
        ...
    </head>
    <body>
        ...
        <!-- Payment panel tag -->
        <div id="paymentForm">
        </div>
        ...
    </body>
</html>


Step 3 : Initiate a Cash-in to get payment URL and Token

The following data have to be retrieved from the response body of the service "CASH-IN initiation" :

  • the payment service URL (payment_url)
  • a payment token (payment_token)


Step 4 : Call JS function

The function SecureCb.injectionIframe has to be called to inject the payment panel.

<html>
    <head>
        ...
        <!-- JS library import -->
        ...
    </head>
    <body>
        ...
        <!-- Payment panel tag -->
        <div id="paymentForm">
        </div>
        ...
        <script>
            ...
            var paymentURL = 'https://secure-cb.w-ha.com/secure-node-ems/purchase-form'; <!-- this value should be obtained from CASH_IN initiation response -->
            var paymentToken = '654fsd4fs6d4fsd64fs6d4fs6d4fs6dfsdfsdf54f'; <!-- this value should be obtained from CASH_IN initiation response -->
            var styleCSSCustom = {};
 
            <!-- JS function call : Iframe injection -->
            SecureCb.injectIframe('paymentForm', paymentURL, paymentToken, styleCSSCustom);
            ...
         </script>
    </body>
</html>

The SecureCb.injectionIframe() parameters are :

  • The ID of the <div> tag that will be replaced by the payment panel
  • The payment service URL
  • The payment token
  • Optional : Custom CSS style to apply to the payment panel (see dedicated section)


Custom panel content

To customize the payment form panel it is possible to redefine all or some content elements of the panel (for example, override only the error messages).

  • In case of partial customization, the overrided tags are used to replace the elements with the same ID into a default form template.
    In this case the provided tags order are NOT considered.

  • In case of complete customization, the form content are entirely redefined.
    A customization are considered as complete when the following inputs using those IDs are overrided : creditCardNumber, expirationDate and cvx.


The payment panel frame use the framework BootStrap4.

Panel items

ItemsID
Payment cancel buttoncancelButton
Payment validation buttonvalidationButton
Payment authorization error messageauthorizeInvalidFeedback
ItemsLabel IDInput ID

Validation Error Message ID

Credit Card NumbercreditCardNumberLabelcreditCardNumbercreditCardNumberInvalidFeedback
Expiration DateexpirationDateLabelexpirationDateexpirationDateInvalidFeedback
Card Verification ValuecvxLabelcvxcvxInvalidFeedback
Card memorizationmemorizeCreditCardLabelmemorizeCreditCard-


N.B: By default, the validation error messages will be displayed below the input fields into a tag with the class 'invalid-feedback'.

Supported HTML tags

Some HTML tags could not be added in the payment panel for security reasons (i.e <img>, <script> etc). 

The supported tags are :

  • div

  • span

  • label

  • button

  • input

  • h1,h2,h3,h4,h5,h6

  • select

  • p

Each of this tags can define the attributes style, class, id (others will be NOT used). For expirationDate input, the placeholder could also be defined.

Content structure rules

  • To override tags use their IDs (see part 'Panel Items').
  • A customization are considered as complete when the following inputs using those IDs are overrided : creditCardNumber, expirationDate and cvx.
  • For a complete customization, the root node can only have one child node and this child has to be identify by the ID 'creditCardPart'.
  • The content would be completed by the service if some error messages tags are missing.
  • Input labels are not mandatory.
  • No another input can be add.
  • No customization of the input check (apart from error messages).
  • No javascript.
  • No events listening.
  • Deep of the HTML tree is limited to 6 nodes maximum.

  • Data encoding : UTF-8.

  • The value of the attibute 'name' of inputs with IDs creditCardNumber, expirationDate and cvx will be overrided by the service respectively as : ccnum, expirationDate and cvx.

Sample - complete customization

<div id="paymentForm"> <!-- root container -->
 
  <div id="creditCardPart"> <!-- Credit card panel -->
     
    <!-- bank authorization error message -->
    <div class="invalid-feedback" id="authorizeInvalidFeedback">
      Payment authorization failed.
    </div>
     
    <!-- Credit card number input -->
    <div class="form-row">
      <div class="col-md-8 mb-3">
        <label id="creditCardNumberLabel">Credit Card number</label>
        <input class="form-control" id="creditCardNumber">
        <!-- credit card number error message -->
        <div class="invalid-feedback" id="creditCardNumberInvalidFeedback">
          Invalid credit card number (16 digits)
        </div>
      </div>
    </div>
 
    <div class="form-row">
      <!-- Expiration date input -->
      <div class="col-md-4 mb-3" id="expirationDateGroup">
        <label id="expirationDateLabel" for="expirationDate">Expiration Date</label>
        <input class="form-control" id="expirationDate" placeholder="MM/YY">
        <!-- date format error message -->
        <div class="invalid-feedback" id="expirationDateInvalidFeedback">
          Invalid expiration date (MM/YY)
        </div>
      </div>
 
      <!-- CVC (Card Verification Code) input -->
      <div class="col-md-4 mb-3" id="cvxGroup">
        <label for="cvx">Card Verification Code</label>
        <input class="form-control" id="cvx">
        <!-- CVC error message -->
        <div class="invalid-feedback" id="cvxInvalidFeedback">
          Invalid card verification value (3 digits)
        </div>
      </div>
 
    </div>
 
    <!-- Card memorization input -->
    <div class="form-row" id="memorizeCreditCardGroup">
      <div class="col-xs-12 col-md-12">
        <input type="checkbox" class="o-checkbox" id="memorizeCreditCard">
        <label id="memorizeCreditCardLabel" for="memorizeCreditCard">Memorize my card for future payments</label>
      </div>
    </div>
 
    <!-- Buttons -->
    <div class="form-row">
      <div class="col-md-2 mb-3">
        <button class="btn btn-warning" id="cancelButton">Cancel</button>
      </div>
      <div class="col-md-2 mb-3">
        <button class="btn btn-primary" id="validationButton" type="submit">Validate</button>
      </div>
    </div>
 
  </div>
</div>

Sample - partial customization (only error message)

<div id="paymentForm">
 
  <!-- credit card number error message -->
  <div class="invalid-feedback" id="creditCardNumberInvalidFeedback">
    Enter the credit card number (16 digits)
  </div>
 
  <!-- expiration date format error message -->
  <div class="invalid-feedback" id="expirationDateInvalidFeedback">
    Bad date format (MM/YY)
  </div>
 
  <!-- CVC error message -->
  <div class="invalid-feedback" id="cvxInvalidFeedback">
    Enter the card verification value(3 digits)
  </div>
 
</div>

Custom panel style (CSS)

A parameter can be set on the call of SecureCb.injectionIframe to customized the CSS style of the payment panel content.

This parameter is a javascript object. Its description syntax is related to CSS standard.

Selectors and attributes are separated by the comma character ','.

Attributes key and value are both in quotes.

For example :

var styleCSSCustom =
 {
    ".invalid-feedback":{
        "color" : "red",
        "font-weight" : "bold"
    },
    "#GreenLabel":{
        "color" : "green",
        "font-weight" : "bold"
    }
 };


Cash-out services

Cash-out transactions services.

A cash-out transaction is a transaction to extract money from a wallet and transfer money to a bank account.

So to perform a cash-out of a wallet, at least one 'Bank Account' should be added to the associated account.

Notice that cash-out could be performed on wallets owned by STANDARD and BUSINESS accounts but also on wallets owned by the partner itself (EMONEY or FEES wallets).

The API provide two different ways to ask a cash-out transaction :

  1. A single-step way : call a single service
  2. A two-steps way :
    1. First step : call the service to authorize a cash-out transaction.
    2. Second step : call the service to Confirm or to cancel the previously authorized cash-out transaction.

Transfer orders are process on a daily basis. It may take 24 to 48 hours (business days) to appears on the user bank account depending bank processing time.


Execute a single-step cash-out

Create and launch a new cash-out transaction in a single call (no need to confirm).

REQUEST

Operation:   POST /cash-out

Property

Type

Value                            

Description                                                                

partner_ref

String

max size = 64

Partner unique internal reference of the transaction.

N.B : This reference is useful to retrieve transaction status in case of timeout, using :

GET /transactions/partner_ref/{partner_ref}

tagstring

max size = 100

optional

Custom metadata
payment_method

enum

  • BANK_TRANSFER

optional

Payment method

sender_wallet_idstringmax size = 64Id of the wallet where the amount is debited
fees_wallet_id

string

max size = 64

optional

Id of the wallet where the fees are credited
amountdoublemin = 0.01

Amount of the cash-out (fees included).

The user is debited of the amount on his wallet but is paid of amount-fees on his payment mean (e.g. bank account).

feesdouble optional, default = 0

Fees amount taken by the partner

bankaccount_id

stringmax size = 64

Id of a bank account assiociated to the account to be used.

The bank account should be associated to the user account though the dedicated API.

Request Sample
POST /cash-out
{
    "partner_ref" : "REF-CO-A164684461621621",
    "tag" : "My cash-out",
    "sender_wallet_id" : "WE-9876543219876543",
    "fees_wallet_id" : "WF-1234567891234567",
    "amount" : 105,
    "fees" : 5,
    "bankaccount_id" : "BA-4547165764657546"
}

RESPONSE

HTTP statusCase      
201
Success

Body - Property

Type

Value             

Description                          

id

string

max size = 64

Cash-out transaction id

Response Sample
HTTP/1.1 201 CREATED
{
    "id" : "TX-6546914754654751"
}


Create a cash-out Authorization

Create a new cash-out authorization.

The created transaction will remain waiting to be confirmed or cancelled until the appropriate service call.

REQUEST

Operation:   POST /cash-out/authorize

Property

Type

Value                                           

Description

Same parameters as the 1-step transfer request, plus the parameters below:

auth_timeout_delay

integer

maximum = 62208000 (30 days)

optional, default = maximum

Reservation delay in seconds of the transaction amount

Request Sample
POST /cash-out/authorize
{
    "partner_ref" : "REF-CO-A164684461621621",
    "tag" : "My cash-out",
    "sender_wallet_id" : "WE-9876543219876543",
    "fees_wallet_id" : "WF-1234567891234567",
    "amount" : 105,
    "fees" : 5,
    "bankaccount_id" : "BA-4547165764657546",
    "auth_timeout_delay" : 86400
}

RESPONSE

HTTP statusCase      

201

Success

Body - Property

Type

Value                

Description                         

id

string

max size = 64

Cash-out transaction id

Status could only be either CREATED or FAILED at this step.

Response Sample
HTTP/1.1 201 CREATED
{
    "id" : "TX-6546914754654751"
}

Cancel an Authorized cash-out

Cancel an AUTHORIZED cash-out transaction.

REQUEST

Operation:   DELETE /cash-out/[id]

URL - Property

Type

Value

Description                                                                

id

string

max size = 64

Transaction id

Request Sample
DELETE /cash-out/TX-6546914754654751

RESPONSE

HTTP statusCase
204
Success
Body
- None -
Response Sample
HTTP/1.1 204 OK


Confirm an Authorized cash-out

Confirm an AUTHORIZED cash-out transaction.

REQUEST

Operation:   PUT /cash-out/[id]

URL - Property

Type

Value

Description                                                                

id

string

max size = 64

Transaction id

Body
- None -
Request Sample
PUT /cash-out/TX-6546914754654751

RESPONSE

HTTP statusCase
200
Success
Body
- None -
Response Sample
HTTP/1.1 200 OK


Bank Account services

Services about bank accounts creation, deletion and modification.

Notifice that only IBAN from the following countries of the SEPA zone are accepted.

Eurozone countries: Austria (AT), Belgium (BE), Cyprus (CY), Estonia (EE), Finland (FI), France (FR), Germany (DE), Greece (GR), Ireland (IE), Italia (IT), Latvia (LV), Lithuania (LT), Luxembourg (LU), Malta (MT), Netherlands (NL), Portugal (PT), Slovakia (SK), Slovenia (SI), Spain (ES),

Other european union countries: Bulgaria (BG), Croatia (HR), Czech Republic (CZ), Denmark (DK), Hungary (HU), Poland (PL), Romania (RO), Sweden (SE), United Kingdom (GB)

Other european countries: Island(IS) Liechtenstein (LI), Norway (NO)


Add a Bank Account

Add a bank account to an account.

REQUEST

Operation:   POST /bankaccounts

Body - Property

Type

Value

Description

account_id

string

max size = 64

optional, default = the partner account id

Account id

numberstringmax size = 34Bank account number
bicstring

max size = 12

optional

Bank identifier Code
holder_lastnamestring

max size = 64

authorized characters = [a-z] [A-Z] [0-9] / - ? : ( ) . , ' + space

Bank Accout Holder lastname
holder_firstnamestring

max size = 64

authorized characters = [a-z] [A-Z] [0-9] / - ? : ( ) . , ' + space

Bank Accout Holder firstname
tagenum

max size = 100

optional

Field used by partner to set some customized information
Request Sample
POST /bankaccounts
{
    "account_id" : "AS-459652557845695458",
    "tag" : "My first bank account",
    "number" : "FI1370001540000072",
    "bic" : "PSPBFIHH",
    "holder_lastname" : "Dubois",
    "holder_firstname" : "Michel"
}

RESPONSE

HTTP statusCase
201
Success

Body - Property

Type ValueDescription
id stringmax size = 64 Bank account id
Response Sample
HTTP/1.1 201 CREATED
{
    "id" : "BA-6876432164464461"
}


Get a Bank Account

Get a bank account assiociated with an account.

REQUEST

Operation:   GET /bankaccounts/[id]

URL - Property

Type

Value

Description                                                                

id

string

max size = 64

Bank account id

Request Sample
GET /bankaccounts/AS-6876432164464461

RESPONSE

HTTP statusCase                                                      
200
Success

Body - Property

Type

Description                                                                

bankaccountBANK_ACCOUNTBank account data
Response Sample
HTTP/1.1 200 OK
{
    "id" : "BA-6876432164464461",
    "account_id" : "A-459652557845695458",
    "creation_date" : "2017-09-25T12:01:18+0100",
    "tag" : "My first bank account",
    "type" : "IBAN",
    "status" : "ACTIVE",
    "number" : "FI137XXXXXXXX00072",
    "bic" : "PSPBFIHH",
    "holder_lastname" : "Dubois",
    "holder_firstname" : "Michel"
}


Delete a Bank Account

Delete a bank account assiociated to an account. Bank account can be deleted if it is not required or if account have other associated ACTIVE bank account.

REQUEST

Operation:   DELETE /bankaccounts/[id]

URL - Property

Type

Value

Description                                                                

id

string

max size = 64

Bank account id

Request Sample
DELETE /bankaccounts/BA-6876432164464461

RESPONSE

HTTP statusCase  
204
Success
Body
- None -
Response Sample
HTTP/1.1 204 No Content


Modifiy a Bank Account

Modify a bank account assiociated to an account.

REQUEST

Operation:   PUT /bankaccounts/[id]

URL - Property

Type

Value

Description    

id

string

max size = 64

Bank account id

Body - Property

Type

Value

Description

tagenum

max size = 100

optional

Field used by partner to set some customized information
statusenum
  • ACTIVE
  • INACTIVE

optional

Status of the Bank Account.

Bank account can be set to INACTIVE if it is not required or if account have other associated ACTIVE bank account.

Request Sample
PUT /bankaccounts/BA-6876432164464461
{
    "tag" : "My first bank account",
    "status" : "INACTIVE"
}

RESPONSE

HTTP statusCase 

200

Success
Body
- None -
Response Sample
HTTP/1.1 200 OK


List Bank Accounts

List bank accounts.

REQUEST

Operation:   GET /bankaccounts   ?account_id=[account_id]&per_page=[per_page]&page=[page]

URL - Property

Type

Value

Description

account_id

string

max size = 64

optional

Account id

If defined, returns only bank accounts associated to this account.

per_page

integer

min = 1

max = 100

optional, default = 20

Number of bank accounts per page

pageinteger

min = 1

optional, default = 1

Requested page index

Sample - Request
GET /bankaccounts?per_page=5&page=2
Sample - Request
GET /bankaccounts?account_id=A-459652557845695458

RESPONSE

HTTP statusCase
200
Success
Body - PropertyTypeDescription
bankaccountsBANK_ACCOUNTS []Bank account list
Response Sample
HTTP/1.1 200 OK
{
    "bankaccounts" : [
        {
            "id" : "BA-6446446168764321",
            "account_id" : "A-459652557845695458",
            "creation_date" : "2017-07-13T22:01:18+0100",
            "tag" : "My old bank account",
            "type" : "IBAN",
            "status" : "INACTIVE",
            "number" : "FI135XXXXXXXX00056",
            "bic" : "OKOYFIHH",
            "holder_lastname" : "Dubois",
            "holder_firstname" : "Michel"
        },
        {
            "id" : "BA-6876432164464461",
            "account_id" : "A-459652557845695458",
            "creation_date" : "2017-09-25T12:01:18+0100",
            "tag" : "My last bank account",
            "type" : "IBAN",
            "status" : "ACTIVE",
            "number" : "FI137XXXXXXXX00072",
            "bic" : "PSPBFIHH",
            "holder_lastname" : "Dubois",
            "holder_firstname" : "Michel"
        }
    ]
}



Common Objects

Object

BANK_ACCOUNT

Property

Type

Value

Description

idstringmax size = 64Bank account id
account_idstringmax size = 64Account id
creation_datestring

size = 24

Format : yyyy-MM-dd'T'HH:mm:ss'Z'

Bank account creation date.


tagstringmax size = 100Custom metadata
status

enum

  • ACTIVE
  • INACTIVE

Bank account status

numberstringmax size = 34

Maked IBAN (International Bank Account Number).

The IBAN consists of the country code, two check digits and the account number.

The height digits before the five last ones will be masked (i.e FI137XXXXXXXX00072).

bic

string

max size = 12

optional

The BIC (Business Identifier Code, SWIFT code) that identifies the bank or bank group.
holder_lastnamestring

max size = 64

Bank Accout Holder lastname
holder_firstnamestring

max size = 64

Bank Accout Holder firstname


Credit Cards services

Services about credit cards associated to an account. A Credit card could be associated to an account during the cash-in process.

List Credit Cards

List credit cards (all credit cards or for a specific account).

REQUEST

Operation:   GET /creditcards   ?account_id=[account_id]&per_page=[per_page]&page=[page]

URL - Property

Type

Value

Description

account_id

string

max size = 64

optional

Account id

per_page

integer


min = 1

max = 100

optional, default = 20

Number of credit cards per page

pageinteger

min = 1

optional, default = 1

Requested page number

Request Sample
GET /creditcards?per_page=5&page=2
Request Sample
GET /creditcards?account_id=A-459652557845695458

RESPONSE

HTTP statusCase
200
Success
Body - PropertyTypeDescription
creditcardsCREDIT_CARD []Credit card list
Response Sample
HTTP/1.1 200 OK
{
    "creditcards" : [
        {
            "id" : "CC-4644155946579135",
            "account_id" : "A-459652557845695458",
            "creation_date" : "2017-07-13T22:01:18+0100",
            "tag" : "My master card",
            "brand" : "MASTERCARD",
            "number" : "5105XXXXXXXX5100",
            "expiry_date" : "10/2019"
        },
        {
            "id" : "CC-9465791354644155",
            "account_id" : "A-8989471523654457",
            "creation_date" : "2017-09-25T12:01:18+0100",
            "brand" : "VISA",
            "number" : "4501XXXXXXXX6548",
            "expiry_date" : "02/2020"
        }
    ]
}


Get a Credit Card

REQUEST

Operation:   GET /creditcards/[id]

URL - Property

Type

Value

Description

id

string

max size = 64

Credit card id

Request Sample
GET /creditcards/CC-9465791354644155

RESPONSE

HTTP statusCase
200
Success
Body
creditcardCREDIT_CARDCredit card data
Response Sample
HTTP/1.1 200 OK
{
    "id" : "CC-9465791354644155",
    "account_id" : "A-8989471523654457",
    "creation_date" : "2017-09-25T12:01:18+0100",
    "brand" : "VISA",
    "number" : "4501XXXXXXXX6548",
    "expiry_date" : "02/2020"
}


Delete a Credit Card

Delete a credit card assiociated to an account.

REQUEST

Operation:   DELETE /creditcards/[id]

URL - Property

Type

Value

Description

id

string

max size = 64

Credit card id

Request Sample
DELETE /creditcards/CC-9465791354644155

RESPONSE

HTTP statusCase  
204
Success
Body
- None -
Response Sample
HTTP/1.1 204 OK


Modifiy a Credit Card

Modify a credit card assiociated to an account.

REQUEST

Operation:   PUT /creditcards/[id]

URL - Property

Type

Value

Description

id

string

max size = 64

Credit Card id

Body - Property

Type

Value

Description

tagenum

max size = 100

optional

Field used by partner to set some customized information
statusenum
  • ACTIVE
  • INACTIVE

optional

Status of the Credit Card
Request Sample
PUT /creditcards/CC-9465791354644155
{
    "tag" : "any tag",
    "status" : "INACTIVE"
}

RESPONSE

HTTP statusCase 

200

Success
Body
- None -
Response Sample
HTTP/1.1 200 OK



Common Objects

Object

CREDIT_CARD

Property

Type

Value

Description

idstringmax size = 64Credit card id

account_id

stringmax size = 64Account id (STANDARD OR BUSINESS)
creation_datestring

size = 24

Format : yyyy-MM-dd'T'HH:mm:ss'Z'

Credit card creation date.

tagstringmax size = 100Custom metadata
brandenum
  • VISA
  • MASTERCARD
  • CB

Credit card type

statusenum
  • ACTIVE
  • INACTIVE
Credit Card status
numberstring

size = 16

Credit card number

Only digits from 1 to 4 and 12 to 16 are visible, others are replaced with an 'X'.

Exemple: "4002XXXXXXXX4587"

expiry_datestring

size = 7

Format: MM/YYYY

Credit card expiry date.