Payment Sessions

Une Payment Session est une session de paiement temporaire creee par un merchant. Kadryza assigne un numero de collecte Mobile Money disponible, le client paie ce numero, puis Kadryza confirme le paiement apres reception et rapprochement du SMS credit par la Gateway Android.

⚠️

Le flux Payment Sessions est disponible pour un test terrain controle. Il ne doit pas encore etre considere comme production-grade pour une exposition large a des merchants sans supervision operationnelle.

Flux

Le merchant cree une session via POST /v1/payment-sessions.
Kadryza reserve un collection_number compatible avec l’operateur et l’environnement de la cle API.
Le merchant affiche assigned_collection_number, amount, operator, ticket et expires_at au client final.
Le client paie le numero de collecte.
La Gateway Android remonte un CREDIT_SMS_RECEIVED.
Le backend deduplique, matche, puis confirme uniquement si le match est unique.
Le merchant suit le resultat via webhook ou polling.

Contrat API public

Le contrat public actif est documente dans la reference 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 deduits cote backend depuis la cle API. Ils ne doivent jamais etre envoyes dans le body.

Exemple de reponse

{
  "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 depend de la configuration APP_URL du backend. Sur staging, cette URL doit pointer vers le dashboard de test. Le domaine officiel Kadryza reste a confirmer pour la production publique.

Statuts

Statut	Description
`AWAITING_PAYMENT`	La session attend le paiement client.
`SUCCESS`	Paiement recu, matche de facon unique et confirme.
`UNDER_REVIEW`	Paiement recu mais tardif ou a verifier. Aucun succes automatique.
`EXPIRED`	Session expiree sans paiement confirme.
`FAILED`	Etat reserve pour un futur chemin d’echec explicite.
`CANCELLED`	Session annulee par le merchant pendant `AWAITING_PAYMENT`.

Webhooks actifs

Les evenements 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 evenements test portent aussi :

X-Kadryza-Test: true

Le webhook payment_session.cancelled n’est pas encore emis. Le webhook payment_session.failed existe comme type reserve, mais il ne doit pas encore etre traite comme un evenement actif.

Regles importantes

L’assignation du numero n’est pas aleatoire pure : elle depend de l’operateur, de l’environnement, de la disponibilite, de la capacite et d’une Gateway active.
Une session a toujours une expiration.
Un paiement ambigu ne doit jamais etre transforme automatiquement en SUCCESS.
Les sessions test peuvent atteindre SUCCESS, mais ne creent pas de ledger reel.
Le client Gateway Android ne decide jamais du statut financier ; il transmet seulement le SMS credit et les champs parses.

Avant un test terrain

Suivez le runbook pre-test terrain avant tout vrai paiement, meme de faible montant.

Intégration Express.js Runbook pré-test terrain