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: 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

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

Movement

The movement are all the bank operation that happen in your wallet, with amount, fee and source associated.

HTTP Request

GET https://test-api.centralpay.net/v2/rest/movement/{{movementId}}

HTTP Response

OBJ Json wallet type

Example of curl code

curl -v https://test-api.centralpay.net/v2/rest/movement/2cec85cc-5501-4516-9bdc-a31bdd47d79b \
-u 'doctest:4I9HJRTd'

Back to JSON Format

{
    "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.

HTTP Parameters
movementId UUID (36)	CentralPay ID of the movement Required: yes Validation: UUID

HTTP Request

GET https://test-api.centralpay.net/v2/rest/movement/{{movementId}}

HTTP Response

OBJ Json wallet type

Example of curl code

curl -v https://test-api.centralpay.net/v2/rest/movement/2cec85cc-5501-4516-9bdc-a31bdd47d79b \
-u 'doctest:4I9HJRTd'

Back to JSON Format

{
    "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": ""
}

HTTP Request

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

HTTP Response

List OBJ Json movement type

Example of curl code

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

Back to JSON Format

{
    "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.

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

HTTP Request

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

HTTP Response

List OBJ Json movement type

Example of curl code

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

Back to JSON Format

{
    "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

JSON ATTRIBUTES
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)

cURL
JSON