{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Common scenarios","description":"Shift4 Payment Platform REST API."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"common-scenarios","__idx":0},"children":["Common scenarios"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each scenario below starts with the integration choice — ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/hosted-checkout"},"children":["Hosted checkout"]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components"},"children":["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."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#e-commerce-on-your-own-site"},"children":["E-commerce on your own site"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#fastest-path-to-a-payment"},"children":["Fastest path to a payment"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#customer-chosen-amounts"},"children":["Customer-chosen amounts"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#save-a-card-without-charging"},"children":["Save a card without charging"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#auth-now-capture-on-fulfilment"},"children":["Auth now, capture on fulfilment"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"e-commerce-on-your-own-site","__idx":1},"children":["E-commerce on your own site"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"this-is-for-you-if","__idx":2},"children":["This is for you if"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You have a product or cart page and want the customer to pay there, on your domain, in your layout."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"recommended-approach-payment-components","__idx":3},"children":["Recommended approach: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Payment components"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"set-it-up","__idx":4},"children":["Set it up"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/create-a-checkout-session"},"children":["Create a Checkout Session"]}," per order, with a line item per product and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["collectShippingAddress: true"]}," if you need a delivery address — for card payments, pass the collected address to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components/card-payments#billing-and-shipping-addresses"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["continue()"]}]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendorReference"]}," (your order ID) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}," for reconciliation — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/create-a-checkout-session#other-options"},"children":["Other options"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Mount the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components/card-payments"},"children":["card components"]}," and, optionally, the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components/apple-pay"},"children":["Apple Pay"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components/google-pay"},"children":["Google Pay"]}," buttons alongside them."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/confirm-payment"},"children":["Confirm the payment"]}," server-side before fulfilling the order."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"fastest-path-to-a-payment","__idx":5},"children":["Fastest path to a payment"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"this-is-for-you-if-1","__idx":6},"children":["This is for you if"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You want to accept a payment from your backend with no frontend work at all."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"recommended-approach-hosted-checkout","__idx":7},"children":["Recommended approach: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Hosted checkout"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No script, no public key — redirect the customer to the Checkout Session's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]}," and let ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pay.shift4.com"]}," do the rest."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"set-it-up-1","__idx":8},"children":["Set it up"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/create-a-checkout-session"},"children":["Create a Checkout Session"]}," with your line items and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}," back to your site — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/hosted-checkout"},"children":["Hosted checkout"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhookUrl"]}," so completion reaches your backend even if the customer never returns — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/confirm-payment#webhooks"},"children":["Webhooks"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you don't even want to handle the redirect yourself, consider a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/payment-links/"},"children":["Payment Link"]}," instead — a shareable URL wrapping the same hosted checkout."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"customer-chosen-amounts","__idx":9},"children":["Customer-chosen amounts"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"this-is-for-you-if-2","__idx":10},"children":["This is for you if"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The customer decides what to pay — pay-what-you-want pricing, a tip, or a donation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"recommended-approach-hosted-checkout-1","__idx":11},"children":["Recommended approach: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Hosted checkout"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Customer-chosen amounts are collected on the hosted checkout page and aren't supported by Payment components yet, so this scenario uses Hosted checkout."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"set-it-up-2","__idx":12},"children":["Set it up"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Give the line item's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," preset amounts (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]},"), a custom amount range (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom.min"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max"]},"), or both — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/create-a-checkout-session#amount-fixed-or-customer-chosen"},"children":["Amount: fixed or customer-chosen"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Then hand off as usual: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/hosted-checkout"},"children":["redirect"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"save-a-card-without-charging","__idx":13},"children":["Save a card without charging"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"this-is-for-you-if-3","__idx":14},"children":["This is for you if"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You want a validated card on file — for a later charge, a subscription-like flow, or to vet a payment method before fulfilment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"recommended-approach-either","__idx":15},"children":["Recommended approach: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["either"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A card-verification Checkout Session runs a $0 authorization instead of a charge."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"set-it-up-3","__idx":16},"children":["Set it up"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create the Checkout Session with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action: \"card_verification\""]},", a top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowSavedCards: true"]},", and a defined ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer"]},"; no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lineItems"]}," — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/create-a-checkout-session#card-verification-authorization-checkout-sessions"},"children":["Card-verification Checkout Sessions"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/confirm-payment"},"children":["Confirm"]}," as usual: the Checkout Session reports the verification outcome and the card token for later use."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"auth-now-capture-on-fulfilment","__idx":17},"children":["Auth now, capture on fulfilment"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"this-is-for-you-if-4","__idx":18},"children":["This is for you if"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deposits, pre-orders, delayed shipping — you want to reserve the funds now and take them when you deliver."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"recommended-approach-either-1","__idx":19},"children":["Recommended approach: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["either"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authorization behaviour is a property of the Checkout Session."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"set-it-up-4","__idx":20},"children":["Set it up"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create the Checkout Session with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capture: false"]}," — the resulting charge is authorized but not captured; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/create-a-checkout-session#other-options"},"children":["Other options"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After payment, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/confirm-payment"},"children":["retrieve the Checkout Session"]}," and store ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastTransaction.transaction.invoice"]}," and the card token."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Capture when you fulfil, using the standard transaction capture — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/capturing-sales"},"children":["Capturing Sales"]},"."]}]}]},"headings":[{"value":"Common scenarios","id":"common-scenarios","depth":1},{"value":"E-commerce on your own site","id":"e-commerce-on-your-own-site","depth":2},{"value":"This is for you if","id":"this-is-for-you-if","depth":4},{"value":"Recommended approach: Payment components","id":"recommended-approach-payment-components","depth":4},{"value":"Set it up","id":"set-it-up","depth":4},{"value":"Fastest path to a payment","id":"fastest-path-to-a-payment","depth":2},{"value":"This is for you if","id":"this-is-for-you-if-1","depth":4},{"value":"Recommended approach: Hosted checkout","id":"recommended-approach-hosted-checkout","depth":4},{"value":"Set it up","id":"set-it-up-1","depth":4},{"value":"Customer-chosen amounts","id":"customer-chosen-amounts","depth":2},{"value":"This is for you if","id":"this-is-for-you-if-2","depth":4},{"value":"Recommended approach: Hosted checkout","id":"recommended-approach-hosted-checkout-1","depth":4},{"value":"Set it up","id":"set-it-up-2","depth":4},{"value":"Save a card without charging","id":"save-a-card-without-charging","depth":2},{"value":"This is for you if","id":"this-is-for-you-if-3","depth":4},{"value":"Recommended approach: either","id":"recommended-approach-either","depth":4},{"value":"Set it up","id":"set-it-up-3","depth":4},{"value":"Auth now, capture on fulfilment","id":"auth-now-capture-on-fulfilment","depth":2},{"value":"This is for you if","id":"this-is-for-you-if-4","depth":4},{"value":"Recommended approach: either","id":"recommended-approach-either-1","depth":4},{"value":"Set it up","id":"set-it-up-4","depth":4}],"frontmatter":{"title":"Common scenarios","description":"Map your use case to the right checkout integration — own-site e-commerce, fastest path to a payment, customer-chosen amounts, saving a card, and auth-then-capture.","markdown":{"lastUpdatedBlock":{"hide":true}},"seo":{"title":"Common scenarios"}},"lastModified":"2026-10-08T08:30:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/core-concepts/checkout/common-scenarios","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}