Utilisation des API CentralPay

Les APIs CentralPay permettent d’interagir de manière sécurisée avec notre plateforme pour créer des comptes, initier des paiements ou automatiser des opérations métiers.

Nos APIs reposent sur le protocole HTTP(S) et utilisent un format de réponse en JSON. L’authentification est obligatoire pour chaque requête, sauf exception précisée.

1. Les APIs disponibles

CentralPay met à disposition deux APIs principales :

API	Description	Accès
API Core Payment	Gère toutes les fonctions liées aux opérations de paiement (initiation, transfert, remboursement, etc.)	Tous les marchands
API Onboarding	Permet la création de comptes de paiement ou de monnaie électronique (enrôlements, wallet, etc.)	Réservée aux marchands mandataires (Agents, DME).

2. URLs des environnements

Deux environnements sont disponibles selon votre étape d’intégration :

Composant	Environnement de TEST	Environnement de PRODUCTION
API Core Payment	https://test-api.centralpay.net/	https://api.centralpay.net/
API Onboarding	https://test-onboarding-api.centralpay.net/	https://onboarding-api.centralpay.net/

Les identifiants d’accès sont différents entre test et production.

Vous pouvez également accéder à votre Portail Marchand à des fins de consultation ou de paramétrage :

Composant	Environnement de TEST	Environnement de PRODUCTION
Portail Marchand	https://test-backoffice.centralpay.net/	https://backoffice.centralpay.net/

3. Authentification API

L’API CentralPay utilise l’authentification HTTP Basic, qui repose sur deux éléments obligatoires à inclure dans chaque appel :

• Identifiant API (login)
• Mot de passe API

Toutes les requêtes doivent être transmises en HTTPS. Ces identifiants sont distincts entre les environnements de test et de production.

Pour récupérer vos identifiants API, suivez les étapes suivantes :

3.1. Étape 1 – Accéder au Portail Marchand

• Pour l’environnement de production : https://backoffice.centralpay.net/
• Pour l’environnement de test : https://test-backoffice.centralpay.net/

3.2. Étape 2 – Ouvrir la section technique

Depuis le menu de navigation : Administration > Mon compte > Technique

• Lien direct en production : https://backoffice.centralpay.net/admin/actor/account#technical_tab
• Lien direct en test : https://test-backoffice.centralpay.net/admin/actor/account#technical_tab

3.3. Étape 3 – Récupérer l’Identifiant API (login)

1. Dans l’onglet Technique, localisez la zone « Identifiant API »
2. Cliquez sur l’identifiant affiché pour l’ouvrir en détail
3. Copiez la valeur indiquée dans le champ Login

⚠️ Ce login est à fournir dans l’en-tête Authorization de vos requêtes (sous forme de base64 avec le mot de passe, voir plus bas).

3.4. Étape 4 – Générer un Mot de passe API

1. Toujours dans le même écran, cliquez sur le bouton Modifier
2. Cliquez ensuite sur Générer un mot de passe
3. Copiez immédiatement le mot de passe généré, attention il n’est affiché qu’une seule fois
4. Cliquez enfin sur Mettre à jour pour valider le nouveau mot de passe

Si vous perdez le mot de passe, vous devrez recommencer cette opération pour en générer un nouveau.

ℹ️ Bonnes pratiques :
- L’identifiant et le mot de passe peuvent être révoqués ou régénérés à tout moment depuis le portail marchand.
- Ne partagez jamais ces identifiants en clair.
- Stockez le mot de passe dans un gestionnaire sécurisé après sa génération.

4. Clé publique Marchand (MerchantPublicKey)

Certains services, comme cardToken, ne nécessitent pas d’identifiant/mot de passe mais uniquement une clé publique marchand (MerchantPublicKey) pour authentifier la requête.

Où la trouver :

• Connectez-vous au Portail Marchand de production ou de test
• Accédez à : Administration > Technique
• Copiez la clé dans la section Merchant Public Key

5. Méthodes HTTP et MIME Types

Nos APIs sont conformes au style REST, avec les méthodes HTTP suivantes :

Méthode	Usage
POST	Création ou mise à jour d’un objet
GET	Recherche ou consultation d’un objet
DELETE	Suppression d’un objet

Les types MIME suivants sont utilisés :

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

Le Content-Type doit être systématiquement précisé dans les en-têtes HTTP.

6. En-têtes HTTP à utiliser

Chaque appel API doit inclure un certain nombre d’en-têtes HTTP correctement renseignés :

En-tête HTTP	Description
Authorization	Encodage HTTP Basic avec l’identifiant et le mot de passe API
Content-Type	Obligatoire pour toutes les requêtes. Doit être : application/x-www-form-urlencoded ou multipart/form-data
User-Agent	Fortement recommandé, utile pour tracer les intégrations
Idempotence-Key (optionnel mais conseillé)	Permet d’éviter les doublons en cas de réémission d’une même requête

7. Idempotence : sécuriser les réémissions

L’en-tête Idempotence-Key permet de garantir qu’une même requête envoyée plusieurs fois avec la même clé ne sera traitée qu’une seule fois.

Cela est particulièrement utile lors d’une erreur réseau ou d’un doute sur la réussite d’un appel.

La valeur de l’en-tête Idempotence-Key est un hachage SHA1 des principaux champs métier de la requête. Elle doit être unique par combinaison fonctionnelle de données. Exemple pour une opération carte :

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

La clé Idempotence-Key est valable pendant 24h maximum sur nos serveurs

8. Réponses HTTP

Chaque réponse retournée par l’API contient des éléments de traçabilité utiles dans les en-têtes :

En-tête HTTP	Description
Request-Id	Identifiant unique attribué à chaque appel. Peut être communiqué au support CentralPay en cas d’analyse ou de litige technique.

La réponse JSON du corps dépend bien sûr de la ressource appelée (paiement, transfert, onboarding…), mais le header Request-Id est systématique.

9. Déclaration de vos domaines pour les services CustomForm

Pour certains services tels que cardToken, qui dépendent des formulaires embarqués (CustomForm), il est nécessaire de déclarer au préalable les domaines web qui hébergent ces formulaires.

Sans cette déclaration, toute tentative d’appel aux services concernés depuis un domaine non autorisé entraînera une erreur 403 (Forbidden).

1. Connectez-vous au Portail Marchand :
   • Production
   • Test
2. Accédez à :
   • Administration > Mon compte > Technique
3. Cliquez sur Modifier
4. Dans le champ Hosts Custom Forms autorisés, saisissez l’URL ou les domaines à autoriser (ex : https://www.votre-site.com)
5. Enregistrez les modifications

Une fois cette étape effectuée, les services comme cardToken pourront être appelés depuis les domaines déclarés, conformément aux règles de sécurité imposées par CentralPay.