Using the CentralPay APIs

Estimated reading: 5 minutes

The CentralPay APIs allow you to securely interact with our platform to create accounts, initiate payments, or automate business operations.

Our APIs are based on the HTTP(S) protocol and use a JSON response format. Authentication is required for every request, unless otherwise specified.

1. Available APIs

CentralPay provides two main APIs:

APIDescriptionAccess
Core Payment APIManages all functions related to payment transactions (initiation, transfer, refund, etc.)All merchants
API OnboardingAllows users to request the creation of Payment Accounts or Electronic Money Accounts (Enrollment, Wallets, etc.)Reserved for Partner Merchants and Intermediary Merchants (Agents, EMD).

2. Environment URLs

Two environments are available, depending on your stage of Integration:

ComponentTest environmentPRODUCTION Environment
Core Payment APIhttps://test-api.centralpay.net/https://api.centralpay.net/
API Onboardinghttps://test-onboarding-api.centralpay.net/https://onboarding-api.centralpay.net/

The login credentials are different for the test environment and the production environment.

You can also access your Merchant Portal to view information or configure settings:

ComponentTest environmentPRODUCTION Environment
Merchant Portalhttps://test-backoffice.centralpay.net/https://backoffice.centralpay.net/

3. API Authentication

The CentralPay API uses HTTP Basic authentication, which requires two mandatory elements to be included in every call:

  • API ID (login)
  • API Password

All requests must be sent via HTTPS. These credentials are different for the Test environment and production environment.

To retrieve your API credentials, follow these steps:

3.1. Step 1 – Access the Merchant Portal

3.2. Step 2 – Open the technical section

From the navigation menu: Administration > My Account > Technical

3.3. Step 3 – Retrievethe API ID (login)

  1. On the ” Technical” tab, locate the “API ID” field
  2. Click on the ID shown to view the details
  3. Copy the value shown in the ” Login” field

⚠️ This login must be included in the Authorization header of your requests (in Base64 format along with the password; see below).

3.4. Step 4 – Generate an API Password

  1. On the same screen, click the ” Edit” button
  2. Then click ” Generate a password“
  3. Copy the generated password immediately; please note that it is displayed only once.
  4. Finally, click ” Update ” to confirm the new password

If you forget your password, you’ll need to repeat this process to generate a new one.

ℹ️ Best Practices:
- The username and password can be revoked or regenerated at any time through the Merchant Portal.
- Never share these credentials in plain text.
- Store the password in a secure password manager after it has been generated.

4. Merchant Public Key (MerchantPublicKey)

Some services, such as cardToken, do not require a username or password but only a Merchant public key (MerchantPublicKey) to authenticate the request.

Where to find it:

  • Log in to the Production or Test Merchant Portal
  • Go to: Administration >, Technical
  • Copy the key into the ” Merchant Public Key” section

5. HTTP Methods and MIME Types

Our APIs follow the REST style and support the following HTTP methods:

MethodUsage
POSTCreating or Updating an Object
GETSearching for or Viewing an Item
DELETEDeleting an Object

The following MIME types are used:

  • application/x-www-form-urlencoded
  • multipart/form-data

The Content-Type must always be specified in the HTTP headers.

6. HTTP Headers to Use

Each API call must include a number of correctly populated HTTP headers:

HTTP HeaderDescription
AuthorizationHTTP Basic Authentication Using the API Username and Password
Content-TypeRequired for all requests. Must be: application/x-www-form-urlencoded or multipart/form-data
User-AgentHighly recommended; useful for plotting integrals
Idempotence-Key (optional but recommended)Prevents duplicates when the same request is resubmitted

7. Idempotence: Ensuring Safe Reissuance

The ` Idempotence-Key ` header ensures that the same request sent multiple times with the same key will be processed only once.

This is particularly useful in the event of a network error or if you are unsure whether a call was successful.

The value of the ` Idempotence-Key ` header is an SHA1 hash of the request’s main business fields. It must be unique for each functional combination of data. Example for a card transaction: 

ℹ️ Idempotence-Key = sha1(card[number] + card[cvc] + card[expirationMonth] + card[expirationYear] + card[check] + merchantPublicKey)

The key ” Idempotence-Key ” is valid for up to 24 hours on our servers

8. HTTP Responses

Each response returned by the API contains useful traceability information in the headers:

HTTP HeaderDescription
Request-IdA unique identifier assigned to each call. This can be provided to CentralPay support in the event of an investigation or technical dispute.

The JSON response body depends, of course, on the resource being called (payment, transfer, onboarding, etc.), but the ` Request-Id ` header is always included.

9. Registering Your Domains for CustomForm Services

For certain services, such as cardToken, that rely on embedded forms (CustomForm), you must first declare the web domains that host these forms.

Without this declaration, any attempt to access the relevant services from an unauthorized domain will result in a 403 (Forbidden) error.

  1. Log in to the Merchant Portal:
  2. Go to:
    • Administration > My Account > Technical
  3. Click ” Edit“
  4. In the ” Allowed Hosts for Custom Forms” field, enter the URL or domains to allow (e.g., https://www.votre-site.com)
  5. Save the changes

Once this step is complete, services such as cardToken can be accessed from the registered domains, in accordance with the security rules imposed by CentralPay.

Using the CentralPay APIs - PreviousTerms and Conditions of UseNext - Using the CentralPay APIsMerchant Portal

Recently visited pages

CONTENTS