Checkout embarqué

Le citoyen paie dans un overlay sur votre portail (iframe + SDK). Le contrat d'intégration impose une règle absolue : le navigateur ne débloque jamais un dossier ; seul le back intégrateur authentifié par sk_ confirme le paiement.

Documentation détaillée

Sujet	Page
SDK, postMessage, distribution	Référence SDK
Paiement agence dans l'iframe	Agence en embed
Paiement par carte en overlay	Paiement par carte
Cas limites et idempotence	Matrice edge cases

Principes de sécurité

1. Le navigateur ne débloque jamais un dossier. onComplete transporte uniquement un completion_token opaque.
2. Trois chemins serveur autoritaires (par priorité) :
   • Webhook HMAC checkout.completed (principal, file durable)
   • POST /checkout/sessions/verify-completion avec sk_ (fermeture synchrone post-embed)
   • GET /checkout/sessions?order_id= avec sk_ (fallback)
3. Hosted inchangé : l'embed exige mode=embedded explicite à la création de session.
4. client_secret session-scoped : jamais loggé, jamais en analytics, jamais persisté côté client au-delà de la session.
5. sk_ strictement serveur : le SDK et l'iframe n'ont accès qu'au client_secret.
6. Origines embed : seules les origines HTTPS configurées peuvent embarquer l'iframe (frame-ancestors, validation parent_origin).
7. postMessage minimal : pas de paid, status, ni order_id dans les messages iframe → parent.
8. Layout iframe : compact (400 px) ou large (760 px), choisi par le SDK selon la largeur viewport (≥ 720 px → large) ou forcé via l'option layout. Détail : Référence SDK.

Créer une session embed

POST /checkout/sessions
Idempotency-Key: {uuid}

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

Réponse 201 (extraits) :

{
  "id": "chs_01JXXXXXXXX",
  "mode": "embedded",
  "client_secret": "chs_secret_...",
  "embed_checkout_url": "https://pay.example.gov/embed/chs_01JXXXXXXXX",
  "checkout_url": "https://pay.example.gov/c/chs_01JXXXXXXXX"
}

• client_secret : affiché une seule fois ; transmettre au front via votre back, jamais sk_.
• Sans origines embed configurées : 422 embed.origins_required.

Origines embed (deux niveaux)

Scope clé API	Source origines	Configuration
platform (eGouv)	Config globale eGouv	Admin → Intégration eGouv
application (ministère direct)	Origines de l'application	Admin application + régie

CSP frame-ancestors et CORS checkout utilisent ces origines. Le paramètre iframe parent_origin est validé contre la liste.

verify-completion (obligatoire côté back)

POST /checkout/sessions/verify-completion
Authorization: Bearer sk_test_...
Content-Type: application/json

{ "completion_token": "cpt_..." }

Avec clé plateforme : ajouter tenant_id dans le corps.

Réponse 200 :

{
  "session_id": "chs_01JXXXXXXXX",
  "order_id": "CJ-2026-88421",
  "status": "completed",
  "paid": true,
  "metadata": { "tribunal": "Brazzaville" }
}

Codes : 404 checkout.completion_token_not_found, 410 checkout.completion_token_expired, 409 checkout.completion_token_consumed (replay idempotent → même 200).

Traitez verify-completion comme confirmation synchrone UI. Conservez le webhook comme file durable (at-least-once).

Paiement par carte en embed

Pour les sessions en devise carte, l'overlay SDK est le parcours recommandé : le citoyen reste sur le portail ministry pendant la redirection acquéreur. Le SDK signale epayment.checkout.pending pendant le collect carte. Détail contrat redirect : Paiement par carte.

Flux eGouv (clé plateforme)

const session = await epayment.post('/checkout/sessions', {
  mode: 'embedded',
  tenant_id: 'minjust',
  service_code: 'casier_judiciaire',
  order_id,
  amount,
}, { headers: { Authorization: `Bearer ${PLATFORM_SK}`, 'Idempotency-Key': ... } });

return { clientSecret: session.client_secret };

Webhooks : fan-out dual vers l'application intégrateur de la régie ciblée et les endpoints eGouv (Intégration eGouv). Voir eGouv.

Flux ministère direct (clé application)

const session = await epayment.post('/checkout/sessions', {
  mode: 'embedded',
  order_id,
  amount,
}, { headers: { Authorization: `Bearer ${APP_SK}`, 'Idempotency-Key': ... } });

Origines : liste configurée sur l'application ministry.

Documentation associée

• Webhooks
• eGouv
• Casier embed