Référence API checkout ministry

Base : https://paymentdev-api.akieni.tech/api/v1

Les partenaires déjà branchés sur le cash-in historique (apiKey, init-checkout, partners/payments) restent sur un contrat déprécié, distinct de celui-ci : Cash-in déprécié.

En-têtes communs :

Authorization: Bearer sk_test_…
Content-Type: application/json

POST /checkout/sessions

Crée une session de paiement. En-tête obligatoire : Idempotency-Key.

Corps de requête

Champ	Type	Obligatoire	Description
order_id	string, 1-200	Oui	Identifiant dossier unique par application
amount	entier > 0	Oui	Montant dû en unités mineures ISO 4217 (voir ci-dessous).
currency	code ISO 4217	Non	Défaut XAF. Mobile money et agence : XAF uniquement. Paiement carte : devises supportées ci-dessous.
mode	"hosted" | "embedded"	Non	Défaut hosted
tenant_id	UUID	Conditionnel	Obligatoire avec clé scope platform
service_code	string, 1-50	Non	Code catalogue régie actif
description	string, 1-200	Non	Libellé citoyen sur le checkout
note	string, 1-500	Non	Note interne régie, invisible citoyen
customer	{ name?, email?, phone? }	Non	Coordonnées pour le reçu
customer_id	string, 1-200	Non	Identifiant client opaque côté SI
metadata	objet string→string	Non	Max 20 clés, clé max 64 car., valeur max 500 car. ; renvoyé dans webhooks
success_url	URL, max 2048	Non	Retour après paiement réussi
cancel_url	URL, max 2048	Non	Retour après abandon

Réponse 201

Champ	Type	Description
id	string	Identifiant session (chs_…)
order_id	string	Echo order_id
amount	entier	Montant dû
currency	string	Devise session (ISO 4217)
status	enum	open, completed, expired, cancelled, failed
paid	boolean	true uniquement si status = completed
payment_ref	string	Référence 16 chiffres (paiement agence)
checkout_url	URL	Page checkout hébergée
embed_checkout_url	URL | null	Iframe embed si mode = embedded
mode	"hosted" | "embedded"	Mode effectif
client_secret	string | null	Secret embed (une fois, si embedded)
expires_at	string ISO 8601	TTL session (24 h par défaut)

Codes HTTP : 201, 400, 401, 409, 422, 429 (generic.rate_limited, 30 req/min/application).

Montants : unités mineures (obligatoire)

amount n'est jamais un montant « humain » en euros ou dollars. C'est toujours l'entier ISO 4217 en plus petite unité de la devise (currency).

Devise	Décimales	amount pour 100 unités majeures	Affichage citoyen
XAF	0	100 → 100 FCFA ; 5000 → 5 000 FCFA	Identique à amount (pas de centimes)
EUR	2	10000 → 100,00 EUR	Centimes ÷ 100
USD	2	10000 → 100,00 USD	Idem
JPY	0	100 → 100 JPY	Identique à amount

Piège fréquent : { "amount": 100, "currency": "EUR" } = 1,00 EUR (100 centimes), pas 100 EUR. Pour 100 EUR : { "amount": 10000, "currency": "EUR" }.

Le mode XAF (mobile money, agence) est inchangé : amount: 5000 reste 5 000 FCFA.

Devises acceptées

Usage	Devises
Défaut	XAF
Mobile money, agence	XAF
Paiement par carte (offer_id: paddle)	USD, EUR, GBP, AUD, CAD, CHF, DKK, NOK, SEK, PLN, HUF, CZK, RON, BGN, MXN, BRL, ARS, CLP, COP, PEN, INR, SGD, HKD, TWD, KRW, JPY, NZD, ZAR, ILS, TRY, AED, SAR, THB, MYR, PHP, IDR, VND

Devise hors liste : 422 generic.validation_failed (« The currency is not supported. »). Détail carte : Paiement par carte.

GET /checkout/sessions/

Retourne une session par identifiant. Même forme de réponse que la création.

Query optionnelle tenant_id (UUID) : contexte clé plateforme.

Codes HTTP : 200, 401, 404.

GET /checkout/sessions

Liste paginée : { items[], page, page_size, total }.

Paramètres query

Paramètre	Type	Description
order_id	string, 1-200	Filtre identifiant dossier
status	enum session	open, completed, expired, cancelled, failed
customer_id	string, 1-200	Filtre client opaque
payment_ref	string, 1-16	Filtre référence agence
tenant_id	UUID	Contexte clé plateforme
page	entier ≥ 1	Défaut 1
page_size	entier 1-100	Défaut selon configuration

Codes HTTP : 200, 400, 401.

POST /checkout/sessions/{id}/cancel

Annule une session encore open et non payée. Corps vide.

Réponse 200 : même forme que la session, avec status: cancelled, paid: false.

Webhook associé : checkout.cancelled (livraison asynchrone, at-least-once).

Codes HTTP : 200, 401, 404, 409 (session déjà terminale).

POST /checkout/sessions/verify-completion

Vérifie un jeton éphémère émis après paiement embed. Usage synchrone côté SI ; le webhook reste le filet durable.

Corps de requête

Champ	Type	Obligatoire	Description
completion_token	string, min 1	Oui	Jeton cpt_… reçu via SDK
tenant_id	UUID	Conditionnel	Requis pour corréler une clé plateforme à la régie cible

Réponse 200

Champ	Type	Description
session_id	string	Identifiant session
order_id	string	Identifiant dossier
status	enum session	État courant
paid	boolean	true si status = completed
notice_id	UUID	Notice de paiement
tenant_id	UUID	Régie
metadata	objet | null	Métadonnées session
service_code	string | null	Code service si résolu
service_label	string | null	Libellé service si résolu

Jeton : TTL ~10 min, usage unique. Rejeu idempotent après consommation → 200 avec état courant.

Codes HTTP : 200, 401, 403, 404 (checkout.completion_token_not_found), 409 (checkout.completion_token_consumed), 410 (checkout.completion_token_expired).

Exemple curl (création hosted, XAF)

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",
    "service_code": "casier_judiciaire",
    "metadata": { "tribunal": "Brazzaville" }
  }'

Exemple curl (création hosted, EUR carte)

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: DIASPORA-2026-100" \
  -d '{
    "order_id": "DIASPORA-2026-100",
    "amount": 10000,
    "currency": "EUR",
    "description": "Paiement diaspora - 100,00 EUR"
  }'

amount: 10000 + currency: EUR = 100,00 EUR. Ne pas envoyer 100 pour viser cent euros.