Common scenarios

Each scenario below starts with the integration choice — Hosted checkout or Payment components — and lists the Checkout Session options that make it work. The full field documentation and payloads live on the pages linked from each scenario.

• E-commerce on your own site
• Fastest path to a payment
• Customer-chosen amounts
• Save a card without charging
• Auth now, capture on fulfilment

You have a product or cart page and want the customer to pay there, on your domain, in your layout.

The card fields and wallet buttons render inside your page, so you keep the customer through the whole flow while Shift4 secures the card data.

• Create a Checkout Session per order, with a line item per product and collectShippingAddress: true if you need a delivery address — for card payments, pass the collected address to continue().
• Set vendorReference (your order ID) and metadata for reconciliation — see Other options.
• Mount the card components and, optionally, the Apple Pay and Google Pay buttons alongside them.
• Confirm the payment server-side before fulfilling the order.

You want to accept a payment from your backend with no frontend work at all.

No script, no public key — redirect the customer to the Checkout Session's url and let pay.shift4.com do the rest.

• Create a Checkout Session with your line items and a redirectUrl back to your site — see Hosted checkout.
• Set webhookUrl so completion reaches your backend even if the customer never returns — see Webhooks.
• If you don't even want to handle the redirect yourself, consider a Payment Link instead — a shareable URL wrapping the same hosted checkout.

The customer decides what to pay — pay-what-you-want pricing, a tip, or a donation.

Customer-chosen amounts are collected on the hosted checkout page and aren't supported by Payment components yet, so this scenario uses Hosted checkout.

• Give the line item's amount preset amounts (options), a custom amount range (custom.min/max), or both — see Amount: fixed or customer-chosen.
• Then hand off as usual: redirect.

You want a validated card on file — for a later charge, a subscription-like flow, or to vet a payment method before fulfilment.

A card-verification Checkout Session runs a $0 authorization instead of a charge.

• Create the Checkout Session with action: "card_verification", a top-level currency, allowSavedCards: true, and a defined customer; no lineItems — see Card-verification Checkout Sessions.
• Confirm as usual: the Checkout Session reports the verification outcome and the card token for later use.

Deposits, pre-orders, delayed shipping — you want to reserve the funds now and take them when you deliver.

Authorization behaviour is a property of the Checkout Session.

• Create the Checkout Session with capture: false — the resulting charge is authorized but not captured; see Other options.
• After payment, retrieve the Checkout Session and store lastTransaction.transaction.invoice and the card token.
• Capture when you fulfil, using the standard transaction capture — see Capturing Sales.