Encaissez par Mobile Money et carte en UEMOA, depuis votre code, en cinq minutes. Bac à sable complet, sans contrat.
Démarrer en cinq minutes
Inscrivez-vous comme développeur : e-mail, pièce d'identité, description du projet. Vous recevez aussitôt une clé khp_test_ et un espace marchand.
Créez un encaissement avec cette clé (ci-dessous), ouvrez l'URL de la page de l'opérateur simulée, payez, puis vérifiez l'état.
Déclarez une URL de webhook dans votre espace pour être prévenu à chaque changement d'état, signé.
Aucun argent réel ne circule en test. Le passage en production demande un dossier d'entreprise validé (KYB).
Si ça ne marche pas du premier coup
401 : la clé doit être collée d'un bloc, sans espace ni retour à la ligne, entre les guillemets de X-API-Key.
422 : le corps JSON exige reference (votre clé d'idempotence), montant entier et moyen (mobile_money, carte…). Le détail renvoyé nomme le champ fautif.
La page de l'opérateur simulée s'ouvre dans un navigateur, avec l'URL complète de la réponse (champ url). En terminal, elle n'affiche que du HTML.
Le payeur a 15 minutes : sans décision, la transaction passe à EXPIRED. C'est le comportement attendu en production aussi.
Authentification
Chaque appel porte votre clé dans l'en-tête X-API-Key (ou Authorization: Bearer). Une clé khp_test_ ne sert qu'en test, une clé khp_live_ qu'en production.
La clé n'est affichée qu'à sa création. Tournez-la depuis votre espace si elle a fuité : l'ancienne cesse immédiatement.
Limites : 120 appels par minute par application ; les comptes développeur ont en plus un quota journalier (2 000 appels).
Portées d'une clé : paiements:lire, paiements:ecrire, remboursements:ecrire, marchand:lire. Chaque réponse porte X-KHORA-Request-Id (à citer au support) et X-KHORA-Pay-Version.
Créer un encaissement
POST /api/v1/pay/transactions crée ET lance la transaction. La réponse contient la transaction et une suite : ce que votre application doit faire pour que le payeur paie.
curl -s -X POST https://api.khorans.net/api/v1/pay/transactions \
-H "X-API-Key: khp_test_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{ "montant": 1000, "devise": "XOF", "moyen": "mobile_money", "operateur": "orange", "reference": "FACTURE-2026-0001", "description": "Facture eau octobre", "payeur": {"telephone": "+2250700000000"} }'| reference | Votre référence unique. C'est la clé d'idempotence : rejouer la même rend la même transaction (200), jamais un doublon. La même référence avec d'autres paramètres est refusée (409). |
| montant | Entier, en unité de la devise. XOF : francs, sans décimales (10.0 est refusé). |
| devise, pays | Déduits du marchand si absents. XOF pour l'UEMOA. |
| moyen | mobile_money (défaut), carte, wallet, sandbox. |
| operateur | mtn, orange, moov, wave pour le Mobile Money ; visa, mastercard pour la carte. |
| payeur | Objet libre : telephone (E.164), nom… Jamais renvoyé en entier. |
| description, meta | Texte libre et données pour vous (meta est renvoyée telle quelle). |
La suite dit le mode : redirection (ouvrir suite.url chez le payeur), push (l'opérateur pousse une demande USSD, afficher suite.instruction), otp (le payeur saisit un code), immediat. Elle donne aussi expire_dans_s : au-delà, la transaction passe EXPIRED d'elle-même.
Réponse
{
"data": {
"transaction": {"id": "76c45141-…", "reference": "FACTURE-2026-0001", "type": "encaissement", "montant": 1000, "devise": "XOF",
"moyen": "mobile_money", "operateur": "orange", "etat": "PENDING", "reference_partenaire": "…", "env": "test",
"cree_le": "2026-11-06T22:02:23Z", "expire_le": "2026-11-06T22:17:23Z", "meta": {"description": "Facture eau octobre"}},
"suite": {"mode": "redirection", "url": "https://…/payer/…", "instruction": null, "expire_dans_s": 900},
"nouvelle": true
}
}Suivre l'état
GET /api/v1/pay/transactions/{id} rend la transaction, ses transitions et ses remboursements. GET /api/v1/pay/transactions?etat=&limite=&avant= liste les vôtres.
POST /api/v1/pay/transactions/{id}/verifier interroge le prestataire maintenant. C'est la seule source de vérité : KHORA PAY ne croit jamais un message, il revérifie chez l'opérateur avant tout changement d'état.
Le plus simple : attendez le webhook, et relisez la transaction si vous avez un doute.
curl -s -X POST https://api.khorans.net/api/v1/pay/transactions/ID_TRANSACTION/verifier -H "X-API-Key: khp_test_VOTRE_CLE"Rembourser
POST /api/v1/pay/transactions/{id}/rembourser avec reference, montant et motif (portée remboursements:ecrire). Partiel ou total ; la somme des remboursements ne dépasse jamais l'encaissement.
La réponse contient le remboursement (transaction fille) et l'encaissement mis à jour : PARTIALLY_REFUNDED ou REFUNDED. Certains prestataires n'acceptent que le remboursement total (501 avec le motif).
curl -s -X POST https://api.khorans.net/api/v1/pay/transactions/ID_TRANSACTION/rembourser \
-H "X-API-Key: khp_test_VOTRE_CLE" -H "Content-Type: application/json" \
-d '{"reference": "RBT-2026-0001", "montant": 500, "motif": "trop perçu"}'Webhooks
Déclarez une URL https dans votre espace (Clés d'API › application). À chaque changement d'état, KHORA PAY envoie un POST JSON signé. Répondez 2xx en moins de 5 s et traitez ensuite.
Signature : X-KHORA-Signature: t=<epoch>,v1=<hex>, avec v1 = HMAC-SHA256(secret, t + "." + corps brut). Refusez si |maintenant − t| > 300 s. Vérifiez sur le corps brut, jamais re-sérialisé.
Chaque événement porte id (evt_…), type et created. Dédoublonnez par id : une livraison peut arriver deux fois, l'ordre n'est pas garanti. En cas de doute, relisez GET /transactions/{id}.
Sans réponse 2xx : relances à 1 min, 5 min, 30 min, 2 h, 12 h, 24 h ×3, puis abandon (visible dans votre espace, renvoi manuel possible).
Types : transaction.pending, transaction.success, transaction.failed, transaction.expired, transaction.requires_review, transaction.refund_pending, transaction.partially_refunded, transaction.refunded, litige.ouvert, litige.clos.
# Ce que KHORA PAY envoie à votre URL (POST, JSON) :
# X-KHORA-Signature: t=1762468800,v1=3f9c… X-KHORA-Event: transaction.success X-KHORA-Delivery: 42
{"id": "evt_42", "type": "transaction.success", "created": "2026-11-06T22:00:00+00:00",
"evenement": "transaction.success", "de": "PENDING",
"transaction": {"id": "…", "reference": "FACTURE-2026-0001", "etat": "SUCCESS", "montant": 1000, "devise": "XOF"}}Bac à sable
Tout se joue sans réseau ni argent. Le montant pilote le scénario :
| se termine par 999 | le prestataire refuse → FAILED |
| se termine par 998 | reste en attente → EXPIRED à l'échéance |
| se termine par 997 | carte : échec 3-D Secure → FAILED |
| se termine par 995 | SUCCESS puis litige ouvert automatiquement (5 jours pour les preuves) |
| autre montant | SUCCESS quand le payeur paie sur la page simulée (Mobile Money, carte) ou à la vérification |
Mobile Money orange/wave = redirection vers une page d'opérateur simulée (Payer / Annuler) ; moov = push ; mtn = otp. La carte ouvre une page hébergée simulée. MTN sandbox réel : numéros …450 succès, …451 échec, …452 attente.
États et erreurs
INITIATED → PENDING → SUCCESS | FAILED | EXPIRED. SUCCESS → REFUND_PENDING → PARTIALLY_REFUNDED | REFUNDED. REQUIRES_REVIEW quand la vérification diverge (un opérateur KHORA tranche).
| 401 | clé absente, inconnue, révoquée ou expirée |
| 403 | portée manquante, ou compte verrouillé |
| 404 | transaction d'un autre marchand, ou inconnue |
| 409 | référence rejouée avec d'autres paramètres |
| 422 | corps invalide (montant décimal, champ manquant…) : le détail nomme le champ |
| 429 | 120 appels/min ou quota journalier atteint |
| 501 | opération non offerte par ce prestataire (ex. remboursement partiel) |
Passer en production
Votre marchand passe en production quand son dossier KYB est validé par KHORA PAY (références de pièces et documents déposés depuis votre espace). Une clé khp_live_ vous est alors remise ; vos clés de test continuent de fonctionner en test.
Mêmes routes, mêmes formes, mêmes webhooks : seule la clé change. Les frais s'appliquent selon la grille de votre contrat et apparaissent dans votre relevé (net, frais, commission).
La même documentation en JSON : https://api.khorans.net/api/v1/pay/doc