{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","cards","card"]},"type":"markdown"},"seo":{"title":"Confirm the payment","description":"Shift4 Payment Platform REST API."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"confirm-the-payment","__idx":0},"children":["Confirm the payment"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session.succeeded"]}," browser event (Payment components) and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status=success"]}," redirect parameter (Hosted checkout) are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["convenience signals"]}," — neither is proof of payment. Always confirm server-side before fulfilling, and treat the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Checkout Session as the source of truth"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retrieve-the-checkout-session","__idx":1},"children":["Retrieve the Checkout Session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve a single Checkout Session by its ID in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutSessionId"]}," header. No request body is required:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://api.shift4.com/api/rest/v1/checkoutsessions/retrieve \\\n  -H \"AccessToken: YOUR_ACCESS_TOKEN\" \\\n  -H \"InterfaceVersion: 1.0\" \\\n  -H \"InterfaceName: YourApp\" \\\n  -H \"CompanyName: YourCompany\" \\\n  -H \"CheckoutSessionId: chse_wMCUGVZgpf45fWHzKbYWMKmZ\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A completed Checkout Session has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: \"paid\""]}," and a populated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastTransaction"]}," — the processor response for the resulting charge:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"result\": [\n    {\n      \"dateTime\": \"2026-05-20T10:44:02Z\",\n      \"checkoutSession\": {\n        \"id\": \"chse_wMCUGVZgpf45fWHzKbYWMKmZ\",\n        \"action\": \"payment\",\n        \"status\": \"paid\",\n        \"expiresAt\": \"2026-05-20T11:30:00Z\",\n        \"vendorReference\": \"vendor_reference\",\n        \"lineItems\": [\n          {\n            \"product\": {\n              \"name\": \"Test Product\",\n              \"amount\": { \"total\": 12.99 },\n              \"currencyCode\": \"USD\"\n            },\n            \"quantity\": 1\n          }\n        ],\n        \"lastTransaction\": {\n          \"dateTime\": \"2026-05-20T03:44:01.000-07:00\",\n          \"card\": {\n            \"type\": \"card_type\",\n            \"token\": { \"value\": \"card_token_value\" },\n            \"number\": \"XXXXXXXXXXXX4242\",\n            \"expirationDate\": 1299\n          },\n          \"amount\": { \"total\": 12.99 },\n          \"merchant\": { \"mid\": \"merchant_mid\" },\n          \"transaction\": {\n            \"invoice\": \"invoice_number\",\n            \"saleFlag\": \"S\",\n            \"responseCode\": \"A\",\n            \"authorizationCode\": \"authorization_code\",\n            \"retrievalReference\": \"retrieval_reference\",\n            \"hostResponse\": {\n              \"reasonCode\": \"00\",\n              \"reasonDescription\": \"Transaction Approved\"\n            },\n            \"cardOnFile\": {\n              \"type\": \"S01\",\n              \"transactionId\": \"transaction_id\"\n            }\n          }\n        }\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A Checkout Session that never completes ends in one of two terminal statuses instead: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]}," (its lifetime elapsed before payment) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," (the maximum number of failed payment attempts was reached)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To review or reconcile activity in bulk rather than one Checkout Session at a time, list Checkout Sessions with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/payments-platform-rest/openapi/checkout-sessions/checkoutsessionslist"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/checkoutsessions/list"]}]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-fields-on-a-paid-checkout-session","__idx":2},"children":["Key fields on a paid Checkout Session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastTransaction"]},", these are the fields you'll reach for most. For the complete response schema — every field on the Checkout Session and its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastTransaction"]}," — see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/payments-platform-rest/openapi/checkout-sessions/checkoutsessionsretrieve"},"children":["Retrieve Checkout Session"]}," API reference."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"280px","data-label":"Field"},"children":["Field "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutSession.status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]}," confirms the payment completed successfully."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.responseCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["A"]}," = approved, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["D"]}," = declined."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.invoice"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invoice number assigned by the processor for this transaction — the key you need for a later capture, refund, or void."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.authorizationCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorization code returned by the card network."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.cardOnFile.transactionId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Network transaction ID for card-on-file linkage."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.saleFlag"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["S"]}," = sale, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["C"]}," = credit (refund)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card.number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Masked PAN of the card used."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutSession.vendorReference"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your internal reference, as supplied at create time."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhooks","__idx":3},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a source of truth that doesn't depend on the customer's browser, consume webhooks instead of (or alongside) polling retrieve."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-it-works","__idx":4},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhookUrl"]}," when you ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/create-a-checkout-session#other-options"},"children":["create the Checkout Session"]}," and Shift4 sends an HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," to that URL for each Checkout Session event — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session_created"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session_completed"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout_session_expired"]}," — carrying the full object. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event.type"]}," to route (the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutSession"]}," below is abbreviated):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"dateTime\": \"2026-06-26T10:15:30.123456Z\",\n  \"event\": {\n    \"type\": \"checkout_session_created\"\n  },\n  \"paymentLink\": null,\n  \"invoice\": null,\n  \"metadata\": {\n    \"orderId\": \"ORD-10042\"\n  },\n  \"checkoutSession\": {\n    \"id\": \"chse_wMCUGVZgpf45fWHzKbYWMKmZ\",\n    \"staticFields\": {\n      \"department\": \"Sales\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"acknowledging-and-retries","__idx":5},"children":["Acknowledging and retries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Respond with any ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2xx"]}," within ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["90 seconds"]}," to acknowledge a webhook. Anything else — a non-2xx status or a timeout — counts as undelivered, and Shift4 retries indefinitely with exponential backoff (after 1, 2, 3, 8, 15, 30, and 60 minutes, then hourly). Return the 2xx as soon as you've recorded the event and do slower processing afterwards."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks are delivered ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["in order across your whole account"]}," — the sequence in which the objects were created, regardless of type. Because delivery is sequential, an undelivered webhook ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["halts the queue"]},": no later webhooks are sent until it succeeds, at which point delivery resumes immediately."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Delivery is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["at least once"]},": a dropped connection before your acknowledgement can cause the same event to arrive twice. There is no idempotency key, so make your handler idempotent — dedupe on the Checkout Session ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event.type"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requests carry no authentication header, so allowlist Shift4's sending endpoints if you need to verify origin. Each webhook carries the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["full"]}," object, in the same format as the API response."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks are sent per Checkout Session, to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhookUrl"]}," you set when you create it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that opening a Payment Link automatically creates a Checkout Session — so Payment Links produce these same Checkout Session webhooks too. For those sessions the link's own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhookUrl"]}," is used, and it takes precedence over any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhookUrl"]}," on the session itself."]},{"$$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/checkoutsessionsnotification"},"children":["Notification"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"after-the-payment","__idx":6},"children":["After the payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The charge behind a paid Checkout Session is managed through the standard transaction operations, keyed by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastTransaction.transaction.invoice"]},". An auth-only Checkout Session (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capture: false"]},") is finalised with a capture, and a settled payment is returned with a refund — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/capturing-sales"},"children":["Capturing Sales"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/processing-refunds"},"children":["Processing Refunds"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":7},"children":["Next steps"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":3,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Test cards","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/checkout/testing"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sandbox card numbers for success, failure, and 3D Secure scenarios."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Capturing Sales","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/capturing-sales"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Understand authorization, capture, and settlement for the resulting charge."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"API reference","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/apis/payments-platform-rest/openapi/checkout-sessions/checkoutsessionsretrieve"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete request and response schema for retrieving Checkout Sessions."]}]}]}]},"headings":[{"value":"Confirm the payment","id":"confirm-the-payment","depth":1},{"value":"Retrieve the Checkout Session","id":"retrieve-the-checkout-session","depth":2},{"value":"Key fields on a paid Checkout Session","id":"key-fields-on-a-paid-checkout-session","depth":2},{"value":"Webhooks","id":"webhooks","depth":2},{"value":"How it works","id":"how-it-works","depth":3},{"value":"Acknowledging and retries","id":"acknowledging-and-retries","depth":3},{"value":"After the payment","id":"after-the-payment","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Confirm the payment","description":"Retrieve the Checkout Session server-side, check status paid and the lastTransaction details, or consume Checkout Session webhooks — the Checkout Session is the source of truth.","markdown":{"lastUpdatedBlock":{"hide":true}},"seo":{"title":"Confirm the payment"}},"lastModified":"2026-10-08T08:30:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/core-concepts/checkout/confirm-payment","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}