CORE FUNCTIONS

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.

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.

HTTP Parameters
<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

HTTP Request

GET https://test-api.centralpay.net/v2/rest/<type_objet>

cURL

HTTP Response

List OBJ Json <type_objet> type

cURL

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

HTTP 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

HTTP Request

GET https://test-api.centralpay.net/v2/rest/<type_objet>

cURL

HTTP Response

List OBJ Json <type_objet> type

cURL

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.

Event Json Service
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 OBJECT 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 OBJECT REFUND_CANCELED > When a REFUND is canceled - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - CHECKENROLLMENT_CREATED > When a 3DS request has been issued - - - - - - - - - - - - - - - - .... DISPUTE OBJECTS RETRIEVAL_NOTICED RETRIEVAL_CLOSE CHARGEBACK_NOTICED CHARGEBACK_WON CHARGEBACK_LOST - - - - - - - - - - - - - - - - SUBSCRIPTION OBJECT SUBSCRIPTIONMODEL_CREATED SUBSCRIPTIONMODEL_UPDATED - - - - - - - - - - - - - - - - SUBSCRIPTION_CREATED SUBSCRIPTION_FAILED SUBSCRIPTION_UPDATED SUBSCRIPTION_CANCELED SUBSCRIPTION_ACTIVE SUBSCRIPTION_FAILURE SUBSCRIPTION_UNPAID SUBSCRIPTION_REACTIVATED - - - - - - - - - - - - - - - - INVOICEITEM_CREATED INVOICEITEM_UPDATED INVOICEITEM_DELETED - - - - - - - - - - - - - - - - INVOICE_CREATED INVOICE_UPDATED INVOICE_CLOSED INVOICE_REOPEN INVOICE_TRANSACTION_SUCCEEDED INVOICE_TRANSACTION_FAILED - - - - - - - - - - - - - - - - . INSTALLEMENT OBJECT INSTALLMENTPAYMENT_CREATED INSTALLMENTPAYMENT_FAILED INSTALLMENTPAYMENT_UPDATED INSTALLMENTPAYMENT_CANCELED INSTALLMENTPAYMENT_ACTIVATED INSTALLMENTPAYMENT_FAILURE INSTALLMENTPAYMENT_PAID INSTALLMENTPAYMENT_UNPAID INSTALLMENT_TRANSACTION - - - - - - - - - - - - - - - - TRANSFER OBJECT TRANSFER_SUCCEEDED TRANSFER_UPDATED TRANSFER_CANCELED - - - - - - - - - - - - - - - - CREDIT OBJECT CREDIT_CREATED > When a credit has been created CREDIT_UPDATED > When a credit has been updated CREDIT_CANCELED > When a credit has been canceled - - - - - - - - - - - - - - - - WEBHOOK linked to an account : PAYOUT OBJECT PAYOUT_CREATED PAYOUT_UPDATED PAYOUT_CANCELED PAYOUT_PAID - - - - - - - - - - - - - - - - WIRETRANSFER OBJECT WIRETRANSFER_CREATED WIRETRANSFER_UPDATED WIRETRANSFER_RECEIVED WIRETRANSFER_CANCELED - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - CUSTOMER_CREATED CUSTOMER_UPDATED - - - - - - - - - - - - - - - - .... - - - - - - - - - - - - - - - - CARD_UPDATED CARDTOKEN_CREATED - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - DEPOSIT_CREATED DEPOSIT_UPDATED - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - ONBOARDING_ENROLLMENT_CREATED > When the onboarding request has been accept. You will receive an enrollementId associated to you custom reference 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

HTTP Request

GET https://test-api.centralpay.net/v2/rest/wallet

HTTP Response

OBJ Json wallet type

Exemple of curl code

curl -v https://test-api.centralpay.net/v2/rest/wallet \
-u 'doctest:4I9HJRTd'

cURL

Back to Json format

{
"available":[{"amount":10,"currency":"EUR"}],
"pending":[{"amount":9,"currency":"EUR"}]}

JSON

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.

HTTP 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

HTTP Request

GET https://test-api.centralpay.net/v2/rest/wallet

HTTP Response

OBJ Json wallet type

Exemple of curl code

curl -v https://test-api.centralpay.net/v2/rest/wallet \
-u 'doctest:4I9HJRTd'

cURL

Back to Json format

{
"available":[{"amount":10,"currency":"EUR"}],
"pending":[{"amount":9,"currency":"EUR"}]}

JSON

Wallet Object

The Json "Wallet" Object

The "Wallet" object response represents a wallet situation at the moment

JSON Attributes
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

cURL
JSON