Flux de paiement

Votre serveur ──POST /checkout-sessions──▶ GC API ──renvoie checkout_url──▶

Client ──visite checkout_url──▶ Page de paiement GC
  │
  ├── Choisit le moyen de paiement
  ├── Saisit la carte
  ├── Authentification 3DS (si requise)
  │
  ├── Succès ──redirection──▶ success_url
  └── Échec ──redirection──▶ failure_url

Votre serveur ──GET /checkout-sessions/{id}──▶ Vérifie le statut (serveur à serveur)

GC ──POST webhook──▶ Votre endpoint webhook (confirmation autoritative)

Les deux sources de vérité

Un paiement a deux confirmations sur lesquelles agir :

1. Redirection du client vers success_url ou failure_url. Utile pour l'UX (afficher "Merci pour votre commande"), mais non autoritative — le client peut fermer le navigateur avant la redirection, le réseau peut tomber, et l'URL ne contient aucune donnée de paiement.
2. Livraison du webhook vers votre endpoint enregistré. Autoritative — déclenchée dès que la passerelle confirme. Avec relances en backoff en cas d'échec.

Que faire après la redirection

GET /api/v1/checkout-sessions/{id}

Utilisez-le dans le handler de redirection pour afficher la page de reçu ou un état intermédiaire "nous confirmons votre paiement". Le statut de session sera completed si le paiement est capturé.

Que faire dans le webhook

Traitez le webhook comme la source de vérité pour la livraison, la logique de remboursement et la comptabilité. Même si le client ne revient jamais sur votre success_url, le webhook se déclenchera quand même.

TIP

Rendez votre logique de livraison idempotente sur transaction_id. Le webhook peut être ré-envoyé — votre code ne doit pas livrer deux fois.

Suite

• Webhooks — payload, vérification de signature, calendrier de relances
• Gestion des erreurs — à quoi ressemblent les échecs et refus