Choose a checkout integration
Select a purchase flow and handle its completion correctly.
| Your starting point | Use | Next step |
|---|---|---|
| An invoice already exists | Its hosted invoice URL | Hosted invoices |
| A reusable offer for many customers | Checkout Link | Checkout Links |
| A known purchase assembled by your server | Checkout Session | Checkout Sessions |
| A shopper is adding/removing products | Cart | Cart Sessions |
| Payment must stay within your page | Session plus hosted iframe | Embed |
Checkout V13 and invoice V6 are hosted UI names. They are not new REST API versions. Use /v2 as today.
Prepare your integration
Use staging credentials and products first. Resolve customer and product UUIDs from the same merchant; display references such as inv_123 are not substitutes for UUID-constrained request fields. Let your server select prices. Browser storefronts send product references through the server-priced Cart surface.
Keep the returned session or invoice URL instead of constructing payment URLs. Associate its identifier with your own order. A redirect is a navigation signal, not payment proof: verify the webhook signature, deduplicate the event, then retrieve current state before fulfilment.
Hosted checkout V13
The customer reviews the merchant, customer, line items, discounts, tax, currency, amount due today, and any later charges. Returning customers can use a saved card after identity checks, trusted-device recognition, and CVV re-entry. New cards can require 3-D Secure. Direct Debit is a scheduled collection, not an instant payment. Wallet eligibility is independent of that card path; see Payment method eligibility.
| Billing shape | Typical amount due today | Apple Pay | Google Pay | Confirm with |
|---|---|---|---|---|
| One-off | The purchase total | Eligible when merchant, origin, and device allow it | Independent of Apple Pay | Payment webhook, then retrieve the payment/invoice |
| Recurring | First period, or zero during a trial | Blocked — future automatic billing needs a reusable method | Independent | Subscription created event plus first invoice state |
| Trial / capped trial | Zero, or the amount after the cap | Blocked | Independent | Trial dates on the subscription; do not treat zero due as a free product |
| Usage / metered | Often zero until usage is billed | Blocked | Independent | Metered item on the subscription; see usage pricing |
| Mixed one-off plus recurring or usage | Combined due-today total | Blocked | Independent | Line-item kinds on the session, not the product catalogue alone |
Direct product-price Checkout Session creation rejects usage prices. A Cart or subscription path that accepts a zero-upfront usage component does not make every session-creation path support usage.
Failure and recovery
| What happened | What to do |
|---|---|
| Card declined | Keep the open session or cart. Offer another eligible method. Do not create a second purchase for the same order. |
| 3-D Secure failed | Collect a different eligible method. Do not reuse the failed authentication result. |
| Expired link or session | Create a new link or session. Do not reconstruct /p/{token} from an old identifier. |
| Repeated Cart convert | Return the existing Checkout Session. Do not create another purchase. |
| Direct Debit pending | Show the collection date and mandate state. Do not mark the order paid. |
| Wallet sheet closed | Offer card or another eligible wallet. Reconcile before retrying. |
Fulfil only after a verified webhook and a server retrieve. Events to expect include checkout started, payment succeeded or failed, and Direct Debit collection pending. Exact event names are on the events page.
Test the whole purchase
Exercise an eligible card payment, authentication, a declined payment, an expired link, a repeated convert request, and a pending Direct Debit journey where configured. Verify discounts, totals, currency, receipts, and fulfilment against the server record. Test Apple Pay and Google Pay independently on supported devices.
For metered products, distinguish selecting a usage price from collecting money for future usage. See Usage pricing and checkout.