Polling et filets de sécurité

Le webhook est le chemin principal de confirmation. Les mécanismes ci-dessous complètent la livraison asynchrone ; ils ne la remplacent pas.

GET session par id

GET https://paymentdev-api.akieni.tech/api/v1/checkout/sessions/{id}
Authorization: Bearer sk_...

Réponse 200 : session (status, paid, payment_ref, expires_at, etc.).

Query optionnelle tenant_id (UUID) pour clé scope platform.

GET par critères (liste)

GET https://paymentdev-api.akieni.tech/api/v1/checkout/sessions?order_id=CJ-2026-88421&page=1&page_size=20

Paramètres query :

Paramètre	Usage
order_id	Retrouver les sessions d'un dossier
status	Filtrer open, completed, failed, cancelled, expired
payment_ref	Filtrer par référence agence (1-16 car.)
customer_id	Filtrer client opaque ministry
tenant_id	Contexte clé plateforme
page, page_size	Pagination (défaut page 1)

Réponse : { items[], page, page_size, total }.

Intervalle recommandé si webhook tardif : backoff progressif (ex. 5 s, 15 s, 30 s), pas de boucle agressive.

verify-completion (embed)

Chemin synchrone après callback onComplete du SDK embed.

POST https://paymentdev-api.akieni.tech/api/v1/checkout/sessions/verify-completion

Corps : { "completion_token": "cpt_…", "tenant_id": "…" } si clé plateforme.

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

Détail : Checkout embarqué.

Annulation

POST https://paymentdev-api.akieni.tech/api/v1/checkout/sessions/{id}/cancel

Session open non payée → status: cancelled, paid: false.

Webhook associé : checkout.cancelled (livraison at-least-once). Pour une logique critique immédiate, confirmer via GET après cancel plutôt que d'attendre uniquement le webhook.

Ordre de priorité recommandé

1. Webhook checkout.completed (handler idempotent sur order_id)
2. verify-completion après embed (même logique métier idempotente)
3. GET ?order_id= si délai anormal (> 30 s sans webhook après paiement supposé)

Clé plateforme (eGouv)

Avec scope platform, inclure tenant_id sur les GET et verify-completion. Les webhooks sont livrés en fan-out dual vers l'application intégrateur de la régie ciblée et les endpoints eGouv (Intégration eGouv).

Préférer verify-completion côté eGouv après embed pour fermeture UX immédiate ; conserver le webhook comme journal durable.

Codes d'erreur utiles au polling

Code	HTTP	Interprétation
checkout.not_found	404	Session inconnue ou clé sans accès à la ressource
checkout.expired	422	Session expirée (TTL dépassé)
checkout.completed	409	Notice déjà payée (nouvelle session inutile)
checkout.session_open	409	Session encore ouverte pour cet order_id

Référence complète : Codes d'erreur.