Aller au contenu
ChadPay
Menu
CONTRAT D'INTÉGRATION OFFICIEL

Documentation API REST ChadPay

Spécification exhaustive des endpoints, structures de requêtes, garanties d'idempotence et codes de réponse HTTP.

1. Authentification & En-têtes HTTP

Toutes les requêtes adressées à l'API ChadPay doivent être sécurisées via une clé API transmise dans l'en-tête standard Authorization sous forme de jeton Bearer.

En-tête Obligatoire Format / Exemple Description
Authorization Oui Bearer cp_test_... / Bearer cp_live_... Clé secrète de votre organisation. Ne doit jamais être exposée côté client.
Idempotency-Key Oui (sur les POST) UUID v4 ou référence unique marchand Garantit qu'une requête dupliquée n'exécute jamais une double transaction économique.
Content-Type Oui application/json Encodage strict JSON en UTF-8.
X-Request-Id Optionnel req_01a... Identifiant de traçabilité injecté ou réémis dans la réponse.

2. Cycle de vie d'un paiement (Flux en 2 étapes)

Pour garantir l'intégrité financière et prévenir toute falsification de montant, l'API ChadPay impose un cycle d'encaissement en deux phases strictes :

  1. Émission du devis canonique (POST /v1/quotes) : Le serveur marchand déclare le montant en XAF, la devise et sa référence. ChadPay verrouille ces paramètres sous un identifiant unique (quo_...) d'une durée de vie de 15 minutes.
  2. Création et exécution du paiement (POST /v1/payments) : Le marchand transmet le quoteId ainsi que les informations de paiement (numéro de téléphone Airtel ou Moov). Le montant est extrait de manière autoritaire du devis vérifié.

3. Endpoints de l'API

POST /v1/quotes — Création d'un devis canonique

Initialise un devis obligatoire avant toute création de paiement. Verrouille le montant en FCFA.

// Requête POST /v1/quotes
{
  "amount": 25000,
  "currency": "XAF",
  "merchantReference": "CMD-2026-891"
}

// Réponse 200 OK
{
  "data": {
    "id": "quo_01a17a...",
    "amount": 25000,
    "currency": "XAF",
    "merchantReference": "CMD-2026-891",
    "status": "active",
    "expiresAt": "2026-10-26T22:30:00Z"
  }
}
POST /v1/payments — Création et déclenchement d'un paiement

Exécute le prélèvement Mobile Money (Airtel ou Moov) auprès de l'opérateur et inscrit l'écriture dans le Grand Livre.

// Requête POST /v1/payments (avec Idempotency-Key obligatoire)
{
  "quoteId": "quo_01a17a...",
  "amount": 25000,
  "currency": "XAF",
  "merchantReference": "CMD-2026-891",
  "paymentMethod": "MOBILE_MONEY",
  "payerMsisdn": "+23591595839",
  "description": "Abonnement annuel service"
}

// Réponse 200 OK
{
  "data": {
    "id": "pay_01a17a...",
    "reference": "PAY-01A17A",
    "status": "completed", // ou "pending" en attente de validation USSD
    "amount": 25000,
    "currency": "XAF",
    "merchantReference": "CMD-2026-891",
    "paymentMethod": "MOBILE_MONEY",
    "rail": "AIRTEL",
    "createdAt": "2026-10-26T22:15:00Z"
  }
}
GET /v1/payments/{id} — Consultation et réconciliation de statut

Renvoie l'état officiel d'une transaction. Pour forcer une vérification auprès de l'opérateur sur un statut incertain, utilisez POST /v1/payments/{id}/sync.

POST /v1/checkout/sessions — Création d'une session de paiement hébergée

Génère une URL de paiement sécurisée ChadPay (/checkout/pay/{token}) prête à intégrer dans un bouton d'achat ou une redirection web.

POST /v1/qr/dynamic — Génération d'un QR code dynamique

Crée un QR code pour borne physique ou écran caisse avec montant prédéfini et expiration temporelle automatique.

4. Statuts de Paiement & Format d'Erreur

Statut Signification Financière Action Marchande
completed Paiement validé et crédité au solde marchand. Définitif et irréversible. Livrer le produit ou débloquer le service.
pending Demande de prélèvement USSD transmise à l'acheteur. En cours. Afficher l'état de chargement et attendre le webhook ou scruter le statut.
status_to_confirm Incertitude réseau ou délai d'attente opérateur. Aucun débit prématuré. Déclencher /sync ou attendre la réconciliation automatique.
failed Refus de l'opérateur, solde insuffisant ou rejet acheteur. Inviter le client à réessayer ou changer de numéro.