Payment Flow

Your Server ──POST /checkout-sessions──▶ GC API ──returns checkout_url──▶

Customer ──visits checkout_url──▶ GC Checkout Page
  │
  ├── Selects payment method
  ├── Enters card details
  ├── 3DS authentication (if required)
  │
  ├── Success ──redirect──▶ success_url
  └── Failure ──redirect──▶ failure_url

Your Server ──GET /checkout-sessions/{id}──▶ Verify status (server-to-server)

GC ──POST webhook──▶ Your webhook endpoint (authoritative confirmation)

The two sources of truth

A payment has two confirmations you can act on:

1. Customer redirect to success_url or failure_url. Useful for UX (show "Thanks for your order"), but not authoritative — the customer can close their browser before redirect, network can fail, and the URL contains no payment data.
2. Webhook delivery to your registered endpoint. Authoritative — fires once the gateway confirms. Retried with backoff on failure.

What to do after redirect

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

Use this in the redirect handler to render the receipt page or show a "we're confirming your payment" interstitial. The session status will be completed if the payment captured.

What to do in the webhook

Treat the webhook as the source of truth for fulfillment, refund logic, and bookkeeping. Even if the customer never returns to your success_url, the webhook will still fire.

TIP

Make your fulfillment idempotent on transaction_id. The webhook can retry — your code should not double-fulfill.

Next

• Webhooks — payload, signature verification, retry schedule
• Error Handling — how failures and declines look