{"data":{"documentation":"Version lisible, avec exemples curl / Python / JavaScript / PHP : page /pay/docs de la plateforme (publique).","commencer":"Pas encore de clé ? Inscription développeur en libre-service : page /pay/inscription de la plateforme (e-mail, pièce d'identité, description du projet) → clé khp_test_ immédiate, bac à sable seul, quota d'appels par jour. Le passage en production exige un dossier d'entreprise (KYB) validé.","authentification":"En-tête X-API-Key: khp_test_… (ou Authorization: Bearer). Une clé test ne sert qu'en test. 120 appels/min.","idempotence":"POST /transactions : `reference` est votre clé. La rejouer rend la même transaction (200), jamais un doublon.","montants":"Entiers, en unité de la devise (XOF sans décimales). 10.0 est refusé.","cycle":"INITIATED → PENDING → SUCCESS | FAILED | EXPIRED ; SUCCESS → REFUND_PENDING → PARTIALLY_REFUNDED | REFUNDED ; REQUIRES_REVIEW si la vérification diverge.","verite":"Un état n'est jamais pris sur la foi d'un message : KHORA PAY revérifie chez le prestataire avant toute transition.","liens_de_paiement":"Sans développement : créez un lien dans l'espace marchand (onglet Liens de paiement), partagez son adresse /pay/l/<id> ; chaque paiement est une transaction ordinaire (référence L-<lien>-<jeton>, meta.lien) notifiée par les webhooks habituels.","abonnements":{"principe":"En Mobile Money rien n'est prélevé automatiquement. Un abonnement émet une ÉCHÉANCE avant chaque période, portée par un lien de paiement à usage unique que vous transmettez à votre client ; impayée, elle est relancée (J+1, J+3, J+7) puis l'abonnement est suspendu après le délai de grâce de l'offre.","routes":["POST /api/v1/pay/abonnements {plan, nom, telephone | reference_client}","GET /api/v1/pay/abonnements/{id}","POST /api/v1/pay/abonnements/{id}/resilier"],"evenements":["abonnement.echeance (echeance.lien_url à transmettre)","abonnement.paye","abonnement.relance","abonnement.suspendu","abonnement.resilie"],"page_publique":"/pay/a/<id de l'offre> : le client s'abonne lui-même."},"paiements_sortants":{"principe":"KHORA PAY ne détient aucun fonds. Vous branchez VOTRE compte opérateur dans l'espace marchand (Paiements sortants) ; un ordre est transmis à l'opérateur avec votre clé et l'argent part de votre portefeuille. En test : bac à sable (montant finissant par 999 → refusé, 998 → en cours, 997 → réponse perdue puis retrouvée). En production : votre compte Wave Business, API de décaissement activée par Wave.","securite":"Portée decaissements:ecrire (jamais donnée par défaut) ET adresse IP appelante inscrite sur le compte ; plafond journalier ; idempotence par reference.","routes":["POST /api/v1/pay/decaissements {reference, montant, telephone, nom?, motif?}","GET /api/v1/pay/decaissements/{id}","POST /api/v1/pay/decaissements/{id}/verifier"],"etats":"INITIATED → PROCESSING → SUCCESS | FAILED ; UNKNOWN = réponse de l'opérateur perdue : l'ordre est relu chez lui, jamais rejoué ; REVERSED = annulé chez l'opérateur.","evenements":["decaissement.success","decaissement.failed","decaissement.reversed"]},"webhooks_sortants":{"entetes":["X-KHORA-Signature: t=<epoch>,v1=<hex>","X-KHORA-Event: transaction.<etat>","X-KHORA-Delivery: <id>"],"verification":"v1 == HMAC-SHA256(secret_application, f\"{t}.{corps_brut}\") et |now − t| ≤ 300 s. Répondre 2xx ; sinon relances à 1 min, 5 min, 30 min, 2 h, 12 h, 24 h ×3 puis abandon.","corps":{"evenement":"transaction.success","de":"PENDING","transaction":"vue publique (id, reference, etat, montant, devise, …)"}},"routes":{"GET /api/v1/pay/moi":"application + marchand","GET /api/v1/pay/moyens?pays=CI":"moyens et opérateurs disponibles pour ce pays (rails actifs de votre environnement)","POST /api/v1/pay/transactions":"créer et lancer — réponse : transaction + suite {mode, url, instruction}","GET /api/v1/pay/transactions?etat=&limite=&avant=":"liste du marchand","GET /api/v1/pay/transactions/{id}":"détail + transitions + remboursements","POST /api/v1/pay/transactions/{id}/verifier":"interroger le prestataire maintenant","POST /api/v1/pay/transactions/{id}/rembourser":"{reference, montant, motif} — portée remboursements:ecrire","POST /api/v1/pay/webhooks/{prestataire}":"réservé aux prestataires (signé par eux)"},"portees":["paiements:lire","paiements:ecrire","remboursements:ecrire","marchand:lire","decaissements:ecrire"],"version":{"courante":"2026-11-06","entete":"X-KHORA-Pay-Version (renvoyé sur chaque réponse) ; X-KHORA-Request-Id = identifiant à citer au support"},"idempotence_stricte":"La même référence avec d'autres paramètres (montant, moyen, opérateur) n'est pas un rejeu : 409.","evenements":"Chaque webhook porte id (evt_…), type, created ; dédoublonnez par id, l'ordre d'arrivée n'est pas garanti ; en cas de doute relisez GET /transactions/{id}.","litiges":"GET /transactions/{id}/litiges ; webhooks litige.ouvert / litige.clos (gagne | perdu | annule). À l'ouverture le montant est retenu au marchand ; il revient si le litige est gagné.","scenarios_bac_a_sable":{"montant se terminant par 999":"le prestataire refuse (FAILED)","montant se terminant par 998":"reste en attente pour toujours (sert à prouver l'expiration)","montant se terminant par 997":"carte : échec de l'authentification 3-D Secure (FAILED)","montant se terminant par 995":"encaissement réussi puis LITIGE ouvert automatiquement (fraude, 5 j pour les preuves)","autre montant":"SUCCESS à la vérification","MTN sandbox":"46733123450 succès · …451 échec · …452 attente"}}}