Checkout hébergé

Mode par défaut : mode absent ou hosted. Le citoyen est redirigé vers la page Epayment (checkout_url).

Créer une session

POST https://paymentdev-api.akieni.tech/api/v1/checkout/sessions
Idempotency-Key: {uuid}

Corps minimum :

{
  "order_id": "CJ-2026-88421",
  "amount": 5000
}

Champ	Obligatoire	Description
order_id	Oui	Identifiant dossier (unique par application)
amount	Oui	Unités mineures ISO 4217. XAF : 5000 = 5 000 FCFA. EUR : 10000 = 100,00 EUR (pas 100). Voir Référence API - Montants.
currency	Non	Défaut XAF ; devises carte pour paiement par carte (voir Référence API)
description	Non	Libellé citoyen (max 200 car.)
note	Non	Note interne régie (max 500 car.), invisible citoyen
customer	Non	{ name, email, phone } pour reçu
customer_id	Non	Identifiant client opaque (max 200 car.)
metadata	Non	Objet strict, max 20 clés ; renvoyé dans webhook
tenant_id	Conditionnel	Obligatoire avec clé plateforme
service_code	Non	Code service régie actif (ex. casier_judiciaire)
success_url / cancel_url	Non	Retour après paiement

Réponse 201 :

{
  "id": "chs_01JXXXXXXXX",
  "order_id": "CJ-2026-88421",
  "amount": 5000,
  "currency": "XAF",
  "status": "open",
  "paid": false,
  "payment_ref": "0120001000483721",
  "checkout_url": "https://pay.example.gov/c/chs_01JXXXXXXXX",
  "mode": "hosted",
  "client_secret": null,
  "embed_checkout_url": null,
  "expires_at": "2026-08-24T12:00:00.000Z"
}

Action SI : rediriger vers checkout_url (HTTP 302 ou lien).

payment_ref : référence 16 chiffres pour paiement en agence. Détail : Paiement agence.

Machine à états session

États de session : open, completed, expired, cancelled, failed.

Règles :

• Une session terminale ne redevient jamais open.
• paid vaut true uniquement si status = completed.
• Après failed, expired ou cancelled : créer une nouvelle session (nouvelle Idempotency-Key, même order_id et même payment_ref possibles via réutilisation de la notice).
• TTL par défaut : 24 h (CHECKOUT_SESSION_TTL_MS).

Correspondance statut terminal / webhook

Statut	Webhook	paid
completed	checkout.completed	true
failed	checkout.failed	false
cancelled	checkout.cancelled	false
expired	checkout.expired	false

Idempotence

• Même Idempotency-Key + même corps → replay même session (pas de second webhook de création).
• Même order_id + nouvelle Idempotency-Key après clôture (failed, expired, cancelled) : retry ministry autorisé.
• 409 checkout.session_open si session encore open.
• 409 checkout.completed si notice déjà payée.

Détail : Idempotence.

Rate limit : 30 req/min/application (429 generic.rate_limited).

Parcours citoyen sur le checkout

1. Choix de l'offre (mobile money, carte ou agence) - voir Mobile money et Paiement par carte.
2. Collect et confirmation PSP ou encaissement agence. Carte : redirection vers page acquéreur (next_action.redirect).
3. Affichage reçu ; redirect success_url si configurée.

Le SI reçoit la confirmation via webhook ; polling optionnel : Polling et filets.

Exemple curl

curl -sS -X POST "https://paymentdev-api.akieni.tech/api/v1/checkout/sessions" \
  -H "Authorization: Bearer sk_test_XXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: CJ-2026-88421" \
  -d '{
    "order_id": "CJ-2026-88421",
    "amount": 5000,
    "description": "Casier judiciaire - Demande n° 88421",
    "metadata": { "tribunal": "Brazzaville" }
  }'

Alternative embed

Si le citoyen ne doit pas quitter le portail métier : Checkout embarqué.