Encaissez par Mobile Money et carte en UEMOA, depuis votre code, en cinq minutes. Bac à sable complet, sans contrat.

Démarrer en cinq minutes

  1. 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.

  2. 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.

  3. 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"} }'
referenceVotre 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).
montantEntier, en unité de la devise. XOF : francs, sans décimales (10.0 est refusé).
devise, paysDéduits du marchand si absents. XOF pour l'UEMOA.
moyenmobile_money (défaut), carte, wallet, sandbox.
operateurmtn, orange, moov, wave pour le Mobile Money ; visa, mastercard pour la carte.
payeurObjet libre : telephone (E.164), nom… Jamais renvoyé en entier.
description, metaTexte 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 999le prestataire refuse → FAILED
se termine par 998reste en attente → EXPIRED à l'échéance
se termine par 997carte : échec 3-D Secure → FAILED
se termine par 995SUCCESS puis litige ouvert automatiquement (5 jours pour les preuves)
autre montantSUCCESS 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).

401clé absente, inconnue, révoquée ou expirée
403portée manquante, ou compte verrouillé
404transaction d'un autre marchand, ou inconnue
409référence rejouée avec d'autres paramètres
422corps invalide (montant décimal, champ manquant…) : le détail nomme le champ
429120 appels/min ou quota journalier atteint
501opé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