Hosted Checkout

Avec le Hosted Checkout, vous ne choisissez pas l’opérateur : vous créez une intention de paiement, redirigez votre client vers checkout_url, et c’est lui qui choisit Airtel Money ou Moov Money sur la page Kadryza. Son choix crée une Payment Session, dont vous suivez le résultat comme d’habitude.

Créer un Hosted Checkout

Portée de clé requise : write_transactions. L’environnement est celui de la clé.

Le détail pricing, lorsqu’il est présent, est figé dès la création de l’intention, avant le choix de l’opérateur. Une répétition de la même intention et sa future Payment Session gardent les mêmes montants, même si le tarif global a changé. amount retourné est le total à payer; le montant original de commande est pricing.original_amount. Voir le contrat de tarification.

curl -X POST https://api.kadryza.app/v1/hosted-checkouts \
  -H "X-API-Key: $KADRYZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order_2026_002",
    "amount": 5000,
    "currency": "XAF",
    "description": "Commande #2026-002",
    "return_url": "https://boutique.example/commande/2026-002"
  }'

{
  "id": "ffd10eac-14d4-4646-a557-495784fcafb8",
  "reference": "order_2026_002",
  "amount": 5000,
  "currency": "XAF",
  "environment": "test",
  "status": "OPEN",
  "expires_at": "2026-06-05T12:40:00Z",
  "created_at": "2026-06-05T12:30:00Z",
  "checkout_url": "https://checkout.kadryza.com/pay/checkout/ffd10eac-14d4-4646-a557-495784fcafb8",
  "return_url": "https://boutique.example/commande/2026-002"
}

Une fois l’opérateur choisi, la réponse (et les lectures suivantes côté page) porte selected_operator et payment_session_id.

Idempotence : recréer avec la même reference et le même contenu (return_url compris) renvoie l’intention existante ; avec un contenu différent, 409 IDEMPOTENCY_CONFLICT.

Retour sur votre site

Avec return_url, la page de paiement renvoie votre client chez vous une fois le paiement réglé :

• paiement confirmé : bouton « Retour sur votre nom » et retour automatique au bout de 3 secondes, que le client peut annuler (une seule fois par paiement, recharger la page ne le relance pas) ;
• en vérification, expiré, échoué ou annulé : bouton de retour, sans redirection automatique.

Kadryza ajoute deux paramètres à votre adresse, en conservant les vôtres :

https://boutique.example/commande/2026-002?kadryza_status=succeeded&kadryza_reference=order_2026_002

Statuts d’une intention

Aucune capacité n’est réservée tant que le client n’a pas choisi : la liste des opérateurs proposés est recalculée à chaque affichage et revérifiée au moment du choix. Si aucun opérateur n’est disponible, la page l’indique au client.

Endpoints utilisés par la page de paiement

Ces endpoints sont publics et appelés par la page hébergée. Vous n’avez pas à les appeler ; ils sont décrits pour comprendre les erreurs visibles par votre client.

Répéter le même choix renvoie la même session : un double clic ne crée pas deux paiements.

Suivre le résultat

Écoutez les webhooks payment_session.succeeded, payment_session.under_review et payment_session.expired (Webhooks). Leur champ data.reference est votre reference. En l’absence de webhook, lisez la session avec GET /v1/payment-sessions/by-reference?reference=….