Payment Sessions

Une Payment Session est une session de paiement temporaire créée par un marchand. Kadryza assigne un numéro de collecte Mobile Money disponible, le client paie ce numéro, puis Kadryza confirme le paiement après avoir constaté le crédit sur le réseau de l’opérateur et l’avoir rapproché de la session. La confirmation n’est jamais présumée.

⚠️

Le flux Payment Sessions est disponible pour un test terrain contrôlé. Ne le considérez pas encore comme production-grade pour une exposition large sans accompagnement Kadryza.

Flux

Le marchand crée une session via POST /v1/payment-sessions.
Kadryza réserve un collection_number compatible avec l’opérateur et l’environnement de la clé API.
Le marchand affiche assigned_collection_number, amount, operator, ticket et expires_at au client final.
Le client paie le numéro de collecte.
Kadryza constate le crédit côté réseau opérateur.
Le paiement est dédupliqué puis rapproché de la session ; la confirmation n’a lieu que si le rapprochement est unique.
Le marchand suit le résultat via webhook ou polling.

Contrat API public

Le contrat public actif est documenté dans la référence API : Payment Sessions.

POST /v1/payment-sessions
GET /v1/payment-sessions/:id
POST /v1/payment-sessions/:id/cancel

Tous ces endpoints utilisent le header public :

X-API-Key: <cle_api_kadryza>

merchant_id, is_test et environment sont déduits côté backend depuis la clé API. Ils ne doivent jamais être envoyés dans le body.

Exemple de réponse

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reference": "order_2026_001",
  "ticket": "KDRZ-8F3K2",
  "amount": 5000,
  "currency": "XAF",
  "operator": "AIRTEL",
  "status": "AWAITING_PAYMENT",
  "environment": "live",
  "assigned_collection_number": "074000001",
  "expires_at": "2026-06-05T12:40:00Z",
  "created_at": "2026-06-05T12:30:00Z",
  "instructions": "Envoyez 5000 XAF vers le numero 074000001 (AIRTEL), puis conservez la reference KDRZ-8F3K2.",
  "checkout_url": "https://dashboard.kadryza.app/pay/payment-sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

checkout_url est construit à partir de la configuration du backend et pointe vers le portail marchand officiel https://dashboard.kadryza.app.

Statuts

Statut	Description
`AWAITING_PAYMENT`	La session attend le paiement client.
`SUCCESS`	Paiement reçu, rapproché de façon unique et confirmé.
`UNDER_REVIEW`	Paiement reçu mais tardif ou à vérifier. Aucun succès automatique.
`EXPIRED`	Session expirée sans paiement confirmé.
`FAILED`	État réservé pour un futur chemin d’échec explicite.
`CANCELLED`	Session annulée par le marchand pendant `AWAITING_PAYMENT`.

Webhooks actifs

Les événements actifs pour Payment Sessions sont :

payment_session.succeeded ;
payment_session.under_review ;
payment_session.expired.

Ils utilisent la signature standard :

X-Kadryza-Signature: sha256=<hmac_hex>

Les événements test portent aussi :

X-Kadryza-Test: true

Le webhook payment_session.cancelled n’est pas encore émis. Le webhook payment_session.failed existe comme type réservé, mais il ne doit pas encore être traité comme un événement actif.

Règles importantes

L’assignation du numéro n’est pas aléatoire pure : elle dépend de l’opérateur, de l’environnement, de la disponibilité et de la capacité du réseau d’encaissement.
Une session a toujours une expiration.
Un paiement ambigu n’est jamais transformé automatiquement en SUCCESS : il part en revue.
Les sessions test peuvent atteindre SUCCESS, mais ne créent aucun mouvement d’argent réel.
Le statut financier est décidé uniquement côté Kadryza, après rapprochement serveur. Rien de ce qui vient du client ne fait foi.

Intégration Express.js Vérification des webhooks