{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","cards","card"]},"type":"markdown"},"seo":{"title":"Create a Checkout Session","description":"Shift4 Payment Platform REST API."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-a-checkout-session","__idx":0},"children":["Create a Checkout Session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Whichever way you take payment — redirecting to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/hosted-checkout"},"children":["Hosted checkout"]}," or embedding ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components"},"children":["Payment components"]}," on your own page — it starts the same way: create a Checkout Session on your backend. The response carries both handoff values: the hosted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]}," and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientSecret"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-the-checkout-session","__idx":1},"children":["Create the Checkout Session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/checkoutsessions/create"]}," from your backend. All authentication and routing values are passed as HTTP headers; the body holds the Checkout Session configuration. For a fixed-price payment, a single line item is enough — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount.total"]}," is in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["major units"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["10"]}," = $10.00), and the Checkout Session currency is inferred from the line items."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.shift4.com/api/rest/v1/checkoutsessions/create \\\n  -H \"AccessToken: YOUR_ACCESS_TOKEN\" \\\n  -H \"InterfaceVersion: 1.0\" \\\n  -H \"InterfaceName: YourApp\" \\\n  -H \"CompanyName: YourCompany\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"checkoutSession\": {\n      \"lineItems\": [\n        {\n          \"product\": {\n            \"name\": \"Order #1234\",\n            \"currencyCode\": \"USD\",\n            \"amount\": { \"total\": 10 }\n          }\n        }\n      ]\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response wraps a single result. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutSession"]}," carries the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chse_…"]},"), the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientSecret"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chcs_…"]},", for Payment components), the hosted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]},"):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"result\": [\n    {\n      \"checkoutSession\": {\n        \"id\": \"chse_wMCUGVZgpf45fWHzKbYWMKmZ\",\n        \"clientSecret\": \"chcs_II2TvLWBrzFniRdjLpgo2zIflaTCzZ5BGPngPZEu0XasgwYRBCHEpyqE0tO9pYoc\",\n        \"url\": \"https://pay.shift4.com/chse_wMCUGVZgpf45fWHzKbYWMKmZ\",\n        \"status\": \"active\"\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is a trimmed example showing only the handoff fields you act on right away. The full Checkout Session object is much richer — it echoes back everything you configured (line items, customer, addresses, custom and static fields, capture and locale settings) plus server-set fields like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresAt"]}," and, once paid, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastTransaction"]},". See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/payments-platform-rest/openapi/checkout-sessions/checkoutsessionscreate"},"children":["Create Checkout Session"]}," reference for the complete schema."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A Checkout Session is valid for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one hour"]},". After that it moves to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]}," status and can no longer be paid — its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresAt"]}," timestamp records exactly when. If a Checkout Session expires before the customer pays, create a new one."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To authenticate, follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/quickstart"},"children":["Quick Start"]}," to exchange your Client GUID and Auth Token for an Access Token, then include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AccessToken"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InterfaceVersion"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InterfaceName"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CompanyName"]}," on every request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["API reference: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/payments-platform-rest/openapi/checkout-sessions/checkoutsessionscreate"},"children":["Create Checkout Session"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-options","__idx":2},"children":["Create options"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The minimal call above is rarely all you want. The most useful ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutSession"]}," options are below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"amount-fixed-or-customer-chosen","__idx":3},"children":["Amount: fixed or customer-chosen"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A line item's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.amount"]}," takes one of two shapes. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," for a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["fixed amount"]}," — the same price every customer pays. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}," and/or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom"]}," for a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["customer-chosen amount"]},", where the customer decides what to pay — useful for donations, tips, or pay-what-you-want pricing. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," is mutually exclusive with the customer-chosen shapes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a fixed amount, set a fixed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," (major units):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"product\": {\n    \"name\": \"Premium Plan\",\n    \"currencyCode\": \"USD\",\n    \"amount\": { \"total\": 49.99 }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a customer-chosen amount, present preset amounts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]},", a custom amount range with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["min"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max"]},"), or both together — give ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom"]}," in the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," to show the preset amounts alongside an \"other amount\" field:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"product\": {\n    \"name\": \"Contribution\",\n    \"currencyCode\": \"USD\",\n    \"amount\": {\n      \"options\": [5, 10, 25],\n      \"custom\": { \"min\": 1, \"max\": 1000 }\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a no-code way to collect customer-chosen amounts, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/payment-links/how-it-works#link-types"},"children":["Payment Links"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"collect-an-address","__idx":4},"children":["Collect an address"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["collectBillingAddress"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["collectShippingAddress"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," to ask the customer for the address (both default to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"). Collected addresses appear on the Checkout Session's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastTransaction"]}," after payment."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"checkoutSession\": {\n    \"lineItems\": [ /* … */ ],\n    \"collectBillingAddress\": true,\n    \"collectShippingAddress\": true\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["How the address is collected depends on the integration. With Hosted checkout, the form asks for it. With Payment components ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["card payments"]},", your page must supply it in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billing"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping"]}," objects passed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["continue()"]}," — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components/card-payments"},"children":["Card payments"]},". For wallet payments (Apple Pay / Google Pay), it is fetched from the wallet automatically."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"custom-and-static-fields","__idx":5},"children":["Custom and static fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFields"]}," to ask the customer for extra information — up to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3"]}," text inputs, each with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key"]}," (your identifier) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}," (shown to the customer, max 20 chars); set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["optional: true"]}," to make one non-mandatory. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["staticFields"]}," to display read-only context (for example an invoice number) — a key-value object of up to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["10"]}," entries."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"checkoutSession\": {\n    \"lineItems\": [ /* … */ ],\n    \"customFields\": [\n      { \"key\": \"shoe_size\", \"label\": \"Shoe size\", \"optional\": false }\n    ],\n    \"staticFields\": { \"Invoice number\": \"ORD-4421\" }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The values the customer enters come back on the Checkout Session's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFields"]}," when you retrieve it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"attach-a-customer","__idx":6},"children":["Attach a customer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Associate a customer in one of three mutually exclusive ways: pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer"]}," with an existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer"]}," with inline details (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["emailAddress"]}," required), or set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutSession.customerCreationPolicy"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]}," to let Shift4 create one."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"checkoutSession\": { \"lineItems\": [ /* … */ ] },\n  \"customer\": { \"id\": \"cust_oM1i4j7EsIY7W5vqqF76diGw\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"other-options","__idx":7},"children":["Other options"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locale"]}," sets the checkout language (defaults to the customer's browser language)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendorReference"]}," is a merchant-defined descriptor reportable on the merchant portal and settlement extract."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowSavedCards"]}," (default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},") lets the customer use a card on file."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capture"]}," (default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},") controls whether the resulting charge is captured immediately. Set it to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," for an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["auth-only"]}," Checkout Session — the charge is authorized now and you capture it later; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/capturing-sales"},"children":["Capturing Sales"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhookUrl"]}," is a destination URL this Checkout Session's webhooks (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session_created"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session_completed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session_expired"]},") are sent to. Set it to receive them — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/confirm-payment#webhooks"},"children":["Confirm the payment"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}," is a flat key-value object for your own use, echoed back on the Checkout Session and never shown to the customer."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"card-verification-authorization-checkout-sessions","__idx":8},"children":["Card-verification (authorization) Checkout Sessions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To authorize a card — confirm it's valid and save it on file ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["without"]}," charging — set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action: \"card_verification\""]},". These Checkout Sessions take ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lineItems"]},", but ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["require"]}," 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"]},". Leave ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capture"]}," unset or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," — a verification charges nothing, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capture: true"]}," is rejected. When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}," is omitted, the Checkout Session defaults to a line-items payment."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"checkoutSession\": {\n    \"action\": \"card_verification\",\n    \"currency\": \"USD\",\n    \"allowSavedCards\": true\n  },\n  \"customer\": { \"id\": \"cust_oM1i4j7EsIY7W5vqqF76diGw\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":9},"children":["Next steps"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":3,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Hosted checkout","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/checkout/hosted-checkout"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redirect the customer to the Checkout Session's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]}," — no client-side code needed."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Payment components","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/checkout/payment-components/"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Embed card fields and wallet buttons on your own page with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientSecret"]},"."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Confirm the payment","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/checkout/confirm-payment"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Verify the Checkout Session server-side before you fulfil."]}]}]}]},"headings":[{"value":"Create a Checkout Session","id":"create-a-checkout-session","depth":1},{"value":"Create the Checkout Session","id":"create-the-checkout-session","depth":2},{"value":"Create options","id":"create-options","depth":2},{"value":"Amount: fixed or customer-chosen","id":"amount-fixed-or-customer-chosen","depth":3},{"value":"Collect an address","id":"collect-an-address","depth":3},{"value":"Custom and static fields","id":"custom-and-static-fields","depth":3},{"value":"Attach a customer","id":"attach-a-customer","depth":3},{"value":"Other options","id":"other-options","depth":3},{"value":"Card-verification (authorization) Checkout Sessions","id":"card-verification-authorization-checkout-sessions","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Create a Checkout Session","description":"Create and configure a Checkout Session on your backend — line items, customer-chosen amounts, addresses, custom fields, customers, and card-verification sessions.","markdown":{"lastUpdatedBlock":{"hide":true}},"seo":{"title":"Create a Checkout Session"}},"lastModified":"2026-10-08T08:30:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/core-concepts/checkout/create-a-checkout-session","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}