CentralPay provides a powerful payment processing API, enabling you to process multi-channel transactions at local and/or international levels.
Introduction
CentralPay API is a REST based API that allows a fast and easy integration of the payment forms. The API uses HTTP to transport and return all responses encoded in JSON.
To simplify integration and testing, CentralPay provides a sandbox where you can carry out your tests.
Authorisations are simulated in test mode.
Test and production modes can be active at the same time - each mode having separate set of public keys and two API ENDPOINT.
We ensure that the data created in test mode will never reach your customers nor cost you any money.
API ENDPOINT
The following link is the core link used to test the API: https://test-api.centralpay.net/
Presentation
The purpose of this document is to present the features of the CentralPay REST API.
By using our Tokenization service and Token.js, sensitive data will not be handled on your servers. The service is fully secure and simplifies your obligations to comply with PCI DSS rules.
2 integration methods are available:
- Push & Pay and Smart Form: Ready-to-use services with automation and pre-integrated functions .
- Custom form: A set of tools that allows you to design your own payment form using our Token.js instructions.
Creation of "Customer" and "Card"
- "Customer" and "Card" allow you to perform recurring payments and track multiple transactions associated with a unique customer.
Marketplace & Plateforme features
- Advanced features to manage marketplaces
- Creation of sub-merchants with attributes management
- Access to a back office that allows to perform transactions analysis and export the results
This new architecture of the API allows us to continuously improve the platform's functionalities and offer new features such as:
- More information on cardholders (issuing country, type of card, category, etc.)
- Directing transactions to specific acquiring accounts
- Fraud detection
- Management of recurring payments
- Managing complex business rules
- Automation system with templates and prefifined actions.
Glossary
cardTokenId | A dematerialized token of the credit card valid for 5 minutes. |
Transaction | An accepted, refused or abandoned credit card transaction made by a Buyer |
PoS | A physical, mobile, or online Point of Sale |
Customer | A consumer or buyer for which means of payment have been registered |
Card | A Payment Card : VISA, Visa Electron, Mastercard, Maestro, American Express, Diners, ... |
Contrat | A Merchant Contract recognized by the card schemes identifying the transactions perfomed |
Wallet |
A Wallet storing the monetary value |
Service access
The test platform url is: https://test-api.centralpay.net/v2/rest/
This test platform allows you to test all the services explained within this documentation.
CentralPay will provide you with connection logs to execute the existing functions.
Functions
All functions use the « MIME » type: "application/x-www-form-urlencoded".
Functions use the following methods:
- HTTP POST method for object creation or update
- HTTP GET method for object search
Authentication
CentralPay API uses "HTTP Basic authentication" for authentication. All requests to our API have to be authenticated (provide the username and the password given by the platform) and have to be made over HTTPS.
If you only plan on using Pop-in forms, you only need to use your "API Secret Key".
You can find your Secret Key in your account settings once you log into your account.
HTTP Request
Always use HTTP-Header for serialization formats (user_agent, ...)
The Content-Type (application/x-www-form-urlencoded or multipart/form-data) must be inquire for all the request in the header.
The use of the « Idempotence-Key » field in the HTTP header request allows to authenticate the request that has been sent.
If the same « Idempotence-Key » value is sent again, the request will be considered as already processed and will not be triggered again.
This check allows the merchant to avoid sending duplicate entries.
Note: The key of « Idempotence-Key » is valid for 24 hours.
HTTP Response
In each HTTP Response, the « Request-Id » field is written in the HTTP header.
Note: If you have a specific request to be sent via CentralPay REST API, please provide us with this information.
Test tools
All functions described in the documentation can be executed with a HTML form (See examples provided in the documentation)
In order to test CentralPay services, different tools are available to check the behaviour of the API (example: Firefox Rest Easy plugin).
Searching methods
Searching methods are the same for all objects.
Requests can use either common or specific parameters.
GET https://test-api.centralpay.net/v2/rest/<type_objet>/<id_objet>
OBJ Json <type_objet> type
Retrieve a single object
This function allows you to retrieve objects with the object ID.
<id_objet> UUID (36) |
CentralPay object ID Required: yes Validation: UUID |
GET https://test-api.centralpay.net/v2/rest/<type_objet>/<id_objet>
OBJ Json <type_objet> type
Retrieve multiple objects
This function allows you to search objects with multiple criteria.
Note: The field « totalCount » displays the total number of objects found from the search request.
Common parameters
before Date ISO 8601 |
Before this date (included) Required: no Note: Included |
after Date ISO 8601 |
After this date (included) Required: no Note: Included |
limit Integer |
Maximum number of T Required: no Validation: > 0 and <= 100 Note: 10 by default |
page Integer |
Page number Required: no Validation: > 0 Note: 1st page by default |
Hooks & Events
Webhook are set to receive Event notification when an action took place.
For example creation of new successful Transaction will result in TRANSACTION_CAPTURED event.
Each event belongs to an existing object:
- TRANSACTION_XXXX belongs to the TRANSACTION object.
- REFUND_XXXX belongs to the REFUND object.
- CUSTOMER_XXXX belongs to the CUSTOMER object.
For each event triggered by a change in the objet, you receive an update posted in JSON format.
You can simply create a page on your website and submit the appropriate URL of that page on your account. Then, each time a new event is created we will call your page back with information about the event.
When a new event is created we will POST to each configured webhook URL. Event data are encoded as JSON and are sent in request body.
To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside this range, including 3xx codes, will indicate to CentralPay that you did not receive the webhook. This means that a URL redirection or a "Not Modified" response will be treated as a failure. If your endpoint returns another value that a 2xx status code, we will send it again every 5 minutes during 2 hours.
Event Service
« Event» is a service used in the hook mecanism.
eventId String (36) |
Event identifier Note: UUID Format |
type String |
Event type are always linked to an existing object
Note: For a list of hooks you can see it here |
creationDate String |
Creation date Note: ISO 8601 |
requestId String (36) |
Request Identifier
Note: UUID Format Request-Id HTTP Response header
|
object |
Event Object Note: Depends of event type, for example it will be a JSON "transaction object" if the event type is "TRANSACTION_CAPTURED" |
Wallet
Wallet is an account with many currencies
GET https://test-api.centralpay.net/v2/rest/wallet
OBJ Json wallet type
curl -v https://test-api.centralpay.net/v2/rest/wallet \
-u 'doctest:4I9HJRTd'
{
"available":[{"amount":10,"currency":"EUR"}],
"pending":[{"amount":9,"currency":"EUR"}]}
Retrieve a wallet
This service allows you to retrieve a wallet with the wallet ID. All the paramers used to search must be passed in the form of queries parameters.
walletId UUID (36) |
CentralPay ID of the wallet Required: no Validation: UUID Wallet of the connected merchant or wallet of one of his sub-merchants By default, the wallet of the connected merchant |
GET https://test-api.centralpay.net/v2/rest/wallet
OBJ Json wallet type
curl -v https://test-api.centralpay.net/v2/rest/wallet \
-u 'doctest:4I9HJRTd'
{
"available":[{"amount":10,"currency":"EUR"}],
"pending":[{"amount":9,"currency":"EUR"}]}
Wallet Object
The Json "Wallet" Object
The "Wallet" object response represents a wallet situation at the moment
available List<WalletItem> |
Wallet available amounts |
currency String |
Currency Note: Favourite format |
amount Integer |
Amount Note: in cents |
pending List<WalletItem> |
Wallet pending amounts Note: |
currency String |
Currency Note: Favourite format |
amount Integer |
Amount Note: in cents |
Movement
The movement are all the bank operation that happen in your wallet, with amount, fee and source associated.
GET https://test-api.centralpay.net/v2/rest/movement/{{movementId}}
OBJ Json wallet type
curl -v https://test-api.centralpay.net/v2/rest/movement/2cec85cc-5501-4516-9bdc-a31bdd47d79b \
-u 'doctest:4I9HJRTd'
{
"movementId": "2cec85cc-5501-4516-9bdc-a31bdd47d79b",
"creationDate": "2020-10-06T12:45:50.756330+02:00",
"expectedAvailabilityDate": "2020-10-08",
"availableDate": "2020-10-08",
"sourceId": "e0a3e218-4f13-4d85-9510-744ae8f0a0d6",
"emissionWalletId": null,
"amount": 1000,
"fee": 0,
"net": 1000,
"currency": "EUR",
"status": "AVAILABLE",
"type": "TRANSACTION",
"description": ""
}
Retrieve Movement
This service allows you to retrieve the movement in your account with the movement ID. All the paramers used to search must be passed in the form of queries parameters.
movementId UUID (36) |
CentralPay ID of the movement Required: yes Validation: UUID |
GET https://test-api.centralpay.net/v2/rest/movement/{{movementId}}
OBJ Json wallet type
curl -v https://test-api.centralpay.net/v2/rest/movement/2cec85cc-5501-4516-9bdc-a31bdd47d79b \
-u 'doctest:4I9HJRTd'
{
"movementId": "2cec85cc-5501-4516-9bdc-a31bdd47d79b",
"creationDate": "2020-10-06T12:45:50.756330+02:00",
"expectedAvailabilityDate": "2020-10-08",
"availableDate": "2020-10-08",
"sourceId": "e0a3e218-4f13-4d85-9510-744ae8f0a0d6",
"emissionWalletId": null,
"amount": 1000,
"fee": 0,
"net": 1000,
"currency": "EUR",
"status": "AVAILABLE",
"type": "TRANSACTION",
"description": ""
}
GET https://test-api.centralpay.net/v2/rest/movement
List OBJ Json movement type
curl -X GET -v https://test-api.centralpay.net/v2/rest/movement \
-u 'doctest:4I9HJRTd'
{
"list": [
{
"type": "MOVEMENT",
"movementId": "5c086774-8939-4a1a-866d-81a4435afa5e",
"creationDate": "2020-11-10T04:02:20.347647+01:00",
"expectedAvailabilityDate": "2020-11-12",
"availableDate": "2020-11-12",
"sourceId": "bc57e362-510f-4196-b13f-44d818148c80",
"emissionWalletId": null,
"amount": 2990,
"fee": 0,
"net": 2990,
"currency": "EUR",
"status": "AVAILABLE",
"type": "TRANSACTION",
"description": ""
},
{
"type": "MOVEMENT",
"movementId": "2decb7fd-0926-4a06-9642-536bef7498f6",
"creationDate": "2020-11-10T04:02:20.241197+01:00",
"expectedAvailabilityDate": "2020-11-12",
"availableDate": "2020-11-12",
"sourceId": "bc57e362-510f-4196-b13f-44d818148c80",
"emissionWalletId": null,
"amount": 0,
"fee": 0,
"net": 0,
"currency": "EUR",
"status": "AVAILABLE",
"type": "AUTHORIZATION",
"description": ""
}
],
"totalCount": 54531
}
List Movement
This function allows you to retrieve all the movements registerered in your account.
currency String (3) |
currency of the movement Required: no |
expectedAvailabilityDateBefore localDate |
Before the expectedAvailabilityDate, this date included.Required: no |
expectedAvailabilityDateAfter localeDate |
After the expectedAvailabilityDate, this date included.Required: no |
availableDateBefore localeDate |
Before the availableDate, this date included.Required: no |
availableDateAfter LocalDate |
After the availableDate, this date included. Required: no |
status Enum MovementStatus |
Arrival date
Required: no Validation: PENDING | PAID | CANCEL
|
type Enum MovementType |
Payout status Required: no Validation: see the different type in the object. |
GET https://test-api.centralpay.net/v2/rest/movement
List OBJ Json movement type
curl -X GET -v https://test-api.centralpay.net/v2/rest/movement \
-u 'doctest:4I9HJRTd'
{
"list": [
{
"type": "MOVEMENT",
"movementId": "5c086774-8939-4a1a-866d-81a4435afa5e",
"creationDate": "2020-11-10T04:02:20.347647+01:00",
"expectedAvailabilityDate": "2020-11-12",
"availableDate": "2020-11-12",
"sourceId": "bc57e362-510f-4196-b13f-44d818148c80",
"emissionWalletId": null,
"amount": 2990,
"fee": 0,
"net": 2990,
"currency": "EUR",
"status": "AVAILABLE",
"type": "TRANSACTION",
"description": ""
},
{
"type": "MOVEMENT",
"movementId": "2decb7fd-0926-4a06-9642-536bef7498f6",
"creationDate": "2020-11-10T04:02:20.241197+01:00",
"expectedAvailabilityDate": "2020-11-12",
"availableDate": "2020-11-12",
"sourceId": "bc57e362-510f-4196-b13f-44d818148c80",
"emissionWalletId": null,
"amount": 0,
"fee": 0,
"net": 0,
"currency": "EUR",
"status": "AVAILABLE",
"type": "AUTHORIZATION",
"description": ""
}
],
"totalCount": 54531
}
Movement Object
movementId UUID |
Movement's id |
creationDate LocalDate |
The date of creation of the movement |
currency String (3) |
Currency of movement |
amount Integer |
Gross amount |
fee Integer |
fee |
net Integer |
Net amount |
description String |
Description |
expectedAvailabilityDate LocalDate |
planned date of avaibility |
availableDate LocalDate |
real date of availibility |
status Enum MovementStatus |
Status of the movement Note: PENDING | PAID | CANCEL |
sourceId UUID |
UUID of the original object |
type Enum MovementType |
type of the movement
Note: TRANSACTION | TRANSACTION_CANCEL | REFUND | REFUND_CANCEL | DISPUTE | DISPUTE_WON | TRANSFER | TRANSFER_CANCEL | TRANSFER_REVERSAL | PAYOUT | PAYOUT_CANCEL | PAYOUT_FAILURE | DEPOSIT | WIRE_TRANSFER | WIRE_TRANSFER_CANCEL | CREDIT | CREDIT_CANCEL| CUSTOMER_CREATION | AUTHORIZATION
|
emissionWalletId UUID |
Wallet of emission of the movement Note : used in the actions with a double movement (transfer and transferReversal) |