Skip to main content
Un encaissement ne se termine pas au moment où vous appelez /pay. Cet appel se contente d’envoyer une demande de confirmation sur le téléphone du client (ou de créer un checkout Wave). Le client valide, l’opérateur confirme à Kori, et c’est seulement alors que votre solde est crédité. Chaque paiement a donc trois états possibles :
pending n’est pas un échec. Un paiement peut rester en attente plusieurs minutes, le temps que le client retrouve son téléphone. Considérez-le comme non résolu, jamais comme refusé.

​
1. Les webhooks — la bonne façon de construire

Abonnez-vous à payment_received et laissez Kori vous prévenir. Aucun polling, aucun minuteur, et cela fonctionne même si personne n’a de navigateur ouvert.
Contenu du webhook
Voir Webhooks pour la vérification de signature et les relances.

​
2. Lire votre transaction

Renvoie l’enregistrement conservé par Kori, status compris. C’est ce que vous utilisez pour un tableau de bord, un travail de rapprochement, ou chaque fois que vous voulez la réponse telle que Kori la connaît actuellement. Nécessite le scope balance.

​
3. Interroger l’opérateur maintenant

Cet appel interroge directement l’opérateur mobile money et règle la transaction si elle a abouti : c’est donc la réponse faisant autorité tant que le paiement est en cours. Il s’utilise avec la reference, pas avec le transaction_id. Il ne demande aucune authentification — la référence fait office de justificatif — ce qui permet à une page de paiement de l’interroger depuis le navigateur du client.
Utilisez-le pendant qu’un client attend le résultat. Pour tout le reste, préférez le webhook : il ne coûte rien et arrive même si le client ferme l’onglet.

​
Si vous devez faire du polling

  • Interrogez toutes les 3 à 5 secondes, pas plus souvent.
  • Arrêtez dès que state vaut success ou failed.
  • Renoncez après environ deux minutes d’attente côté client — mais traitez cela comme « toujours inconnu », pas comme un échec.
  • Un 500 signifie que l’opérateur est injoignable. Réessayez : cela ne dit rien sur le paiement.
Le règlement est idempotent : le webhook, cet endpoint et le réconciliateur interne de Kori peuvent tous résoudre le même paiement, et votre solde n’est crédité qu’une seule fois, quel que soit celui qui arrive en premier.

​
Les paiements jamais confirmés

Si un client ne répond jamais à la demande, le paiement reste pending et Kori le marque expired au bout de 24 heures. Une confirmation tardive vous crédite quand même : expired signifie « nous avons cessé d’attendre », pas « l’argent est perdu ».
Ne concluez jamais qu’un paiement a échoué simplement parce que vous n’en entendez plus parler. Les seuls échecs sont state: "failed" et status: "failed".