Checkout
Checkout Lifecycle
Understand how Checkout Sessions, Invoices, redirects, and webhooks relate.
Checkout Lifecycle
A Checkout Session and an Invoice describe different stages of one payment attempt.
flowchart LR
A[Checkout Session OPEN] -->|Buyer chooses network and token| B[PROCESSING]
B -->|Invoice created| C[Checkout Session COMPLETED]
B -->|Creation failed safely| A
A -->|Session timeout| D[Checkout Session EXPIRED]
C --> E[Invoice PENDING]
E -->|Funds detected| F[Invoice CONFIRMING]
F -->|Enough amount and confirmations| G[Invoice SUCCESS]
E -->|Invoice timeout| H[Invoice EXPIRED]Checkout Session status
| Status | Meaning |
|---|---|
OPEN | The hosted checkout can create its Invoice |
PROCESSING | One request is atomically creating the Invoice |
COMPLETED | The session is linked to an Invoice; payment may still be pending |
EXPIRED | No new Invoice can be created from this session |
The same Checkout Session can create at most one Invoice. Repeated browser submits return the already-linked Invoice instead of creating a second payment address.
Which identifier should you store?
Store all three when available:
| Identifier | Owner | Purpose |
|---|---|---|
merchantOrderId | Your system | Stable lookup of your order |
checkoutSessionId | Yolfi checkout | Correlates redirect, checkout attempt, and webhook |
invoiceId | Yolfi payment | Tracks the blockchain payment lifecycle |
successUrl may include {CHECKOUT_SESSION_ID} for confirmation-page state. Never fulfill from
that redirect. Fulfill only after verifying and processing payment.confirmed idempotently.