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
Use the following link for testing: 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: A ready-to-use service 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 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.
HTTP Request
GET https://test-api.centralpay.net/v2/rest/<type_objet>/<id_objet>
HTTP Response
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 |
HTTP Request
GET https://test-api.centralpay.net/v2/rest/<type_objet>/<id_objet>
HTTP Response
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: WEBHOOK linked to a Point of Sales :
TRANSACTION_SUCCESS > When a transaction has been approved by the issuing bank
TRANSACTION_CANCELED > When a transaction is cancelled TRANSACTION_CAPTURED > When a transaction is sent to the clearing and will be debited TRANSACTION_DISPUTED > When a transaction is turned to a chargeback TRANSACTION_FAILED > When a transaction has been declined by the issuing bank TRANSACTION_FRAUDULENT > When a transaction is refused because it has meet a blacklist element (Email, IP, Card, …) TRANSACTION_NOT_ACCEPTED > When a transaction is refused because entering an acceptance rule TRANSACTION_REFUNDED > When a transaction has been refunded to the card holder TRANSACTION_RISK > When a transaction is refused because of its risk score exceed the limit TRANSACTION_THREEDS_AUTH_FAILED > When a transaction is declined because the card holder failed to authenticate himself during the 3DS process
REFUND_CANCELED - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - CHECKENROLLMENT_CREATED - - - - - - - - - - - - - - - - .... DISPUTE OBJECTS
RETRIEVAL_NOTICED RETRIEVAL_CLOSE CHARGEBACK_NOTICED CHARGEBACK_WON CHARGEBACK_LOST - - - - - - - - - - - - - - - -
SUBSCRIPTIONMODEL_CREATED - - - - - - - - - - - - - - - - SUBSCRIPTION_CREATED - - - - - - - - - - - - - - - - INVOICEITEM_CREATED - - - - - - - - - - - - - - - - INVOICE_CREATED - - - - - - - - - - - - - - - - . INSTALLMENTPAYMENT_CREATED INSTALLMENTPAYMENT_FAILED INSTALLMENTPAYMENT_UPDATED INSTALLMENTPAYMENT_CANCELED INSTALLMENTPAYMENT_ACTIVATED INSTALLMENTPAYMENT_FAILURE INSTALLMENTPAYMENT_PAID INSTALLMENTPAYMENT_UNPAID INSTALLMENT_TRANSACTION - - - - - - - - - - - - - - - -
TRANSFER_SUCCEEDED - - - - - - - - - - - - - - - -
WEBHOOK linked to an account :
PAYOUT_CREATED - - - - - - - - - - - - - - - -
WIRETRANSFER_CREATED WIRETRANSFER_RECEIVED WIRETRANSFER_CANCELED - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - CUSTOMER_CREATED - - - - - - - - - - - - - - - - .... - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - ONBOARDING_ENROLLMENT_STATUS_UPDATED > An ongoing onboarding has been updated
ONBOARDING_ADDITIONAL_DOCUMENT_REQUESTED > Additionnal documents or information have been request on one ongoing onboarding
ONBOARDING_ADDITIONAL_DOCUMENT_UPDATED > Additionnal documents or information have been provided by the account holder in one ongoing onboarding ONBOARDING_PAYMENT_ACCOUNT_CREATED > The account has been created. You receive those elements : merchantEnrollmentId, merchantEnrollmentCustomReference, merchantEnrollmentType, merchantId, merchantName, merchantWalletId, creationDate |
| 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
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 |
HTTP Request
GET https://test-api.centralpay.net/v2/rest/wallet/<walletId>
HTTP Response
OBJ Json wallet type
Exemple of curl code
curl -v https://test-api.centralpay.net/v2/rest/wallet \
-u 'doctest:4I9HJRTd'
Back to Json format
{
"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.
| walletId UUID (36) |
CentralPay ID of the wallet Required: yes Validation: UUID Wallet of the connected merchant or wallet of one of his sub-merchants By default, the wallet of the connected merchant |
HTTP Request
GET https://test-api.centralpay.net/v2/rest/wallet/<walletId>
HTTP Response
OBJ Json wallet type
Exemple of curl code
curl -v https://test-api.centralpay.net/v2/rest/wallet \
-u 'doctest:4I9HJRTd'
Back to Json format
{
"available":[{"amount":10,"currency":"EUR"}],
"pending":[{"amount":9,"currency":"EUR"}]}