Comprendre les Payment Sessions

Une Payment Session est une demande de paiement temporaire. Kadryza réserve un numéro de collecte Mobile Money, votre client y envoie le montant depuis son téléphone, puis Kadryza constate le crédit, le rapproche de la session et décide. La confirmation n’est jamais présumée.

Les paiements réels sont ouverts progressivement. Aujourd’hui, un paiement live reçu est placé en UNDER_REVIEW : Kadryza ne confirme pas automatiquement un paiement réel tant que sa chaîne de preuve n’est pas complète. Intégrez ce statut dès maintenant.

Le flux

Votre serveur crée la session avec la clé API.
Kadryza réserve un numéro compatible avec l’opérateur et l’environnement.
Vous affichez assigned_collection_number, amount, operator, ticket et expires_at — ou vous redirigez vers checkout_url.
Le client paie ce numéro.
Kadryza constate le crédit et le rapproche de cette session.
Vous recevez la décision par webhook.

Règles de rapprochement, vues de votre côté

Un crédit n’est attribué à une session que si le montant, l’opérateur et le numéro correspondent exactement, pendant la fenêtre de la session (et le téléphone du payeur, quand vous l’avez fourni). Conséquences pratiques :

Le montant doit être exact. Un montant différent n’est pas rattaché.
Fournissez customer_phone : il lève les ambiguïtés entre deux paiements du même montant sur le même numéro. Il est obligatoire en live.
Un doute n’est jamais tranché en faveur du succès : un paiement ambigu ou tardif part en UNDER_REVIEW.

Statuts

Statut	Test	Live
AWAITING_PAYMENT	En attente	En attente
SUCCESS	Crédit rapproché de façon unique	Paiement dont la preuve est complète — pas encore ouvert aujourd’hui
UNDER_REVIEW	Paiement arrivé après l’échéance	Paiement reçu à vérifier, ou aucune preuve à l’échéance
EXPIRED	Aucun paiement, 15 min après `expires_at`	— (jamais en live)
CANCELLED	Annulée par vous	— (annulation impossible)

FAILED est un statut réservé, jamais émis aujourd’hui.

Endpoints

Endpoint	Rôle
`POST /v1/payment-sessions`	Créer
`GET /v1/payment-sessions/:id`	Lire
`GET /v1/payment-sessions/by-reference?reference=…`	Retrouver par votre référence
`GET /v1/payment-sessions/:id/webhook-deliveries`	Diagnostiquer les webhooks
`POST /v1/payment-sessions/:id/cancel`	Annuler (test uniquement)
`POST /v1/hosted-checkouts`	Laisser le client choisir l’opérateur

Détails, exemples et erreurs : Payment Sessions, Hosted Checkout.

`checkout_url`

Chaque session renvoie checkout_url, la page de paiement hébergée par Kadryza pour cette session (https://checkout.kadryza.com/pay/payment-sessions/…). Elle est facultative : utilisez-la comme page principale, comme secours, ou pas du tout. Si vous filtrez les domaines de redirection, acceptez checkout.kadryza.com et checkout.kadryza.app.

Webhooks

payment_session.succeeded
payment_session.under_review
payment_session.expired (test)

Signés avec X-Kadryza-Signature, identifiés par event_id / X-Kadryza-Event-ID, marqués X-Kadryza-Test: true en test. Voir Webhooks.

À retenir

Une commande = une reference = une session active.
Ne relancez jamais un paiement pendant AWAITING_PAYMENT ou UNDER_REVIEW.
Le statut financier est décidé uniquement côté Kadryza ; rien de ce que le navigateur affiche ne fait foi.
Une session de test ne crée aucun mouvement d’argent réel.