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 :
- É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. - Création et exécution du paiement (
POST /v1/payments) : Le marchand transmet lequoteIdainsi 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
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. |