{ "session_status": "complete", "payment_required": "required", "amount_cents": 1650, "currency": "USD", "return_to": "https://example.com/calls/7c2a91e4", "charge": { "charge_id": "chg_77386e2f", "status": "succeeded", "amount_cents": 1650, "processor_payment_id": "pay_9J2mQ7bK4dR", "wallet": null }, "cards": [], "default_card_id": null, "caller_first_name": "Dana", "environment": "live", "processor": "square", "business_name": "Blue Bottle Coffee", "voice": "elevenlabs/eleven_turbo_v2_5:nPczCjzI2devNBz1zQrb", "success_message": "You are all set, thanks for calling!", "failure_message": "That card did not go through, I will text you a link.", "tokenization": { "processor": "square", "public_key": "sq0idp-aB3xY7kLmN2pQ9rS", "location_id": "L7Hns8P2M4Q1R", "environment": "production" }, "checkout_session_id": "cs_test_453b5401286d0f80", "merchant_id": "mch_4f2c9a1b7e3d", "order_id": "8QK4M2XJ", "platform_call_id": "call_7c2a91e4", "caller_phone": "+14155550142", "screen": { "decision": "allow", "reasons": [], "notes": [], "attestation": "A", "ported_recently": false, "port_check": "ok", "line_type": "mobile", "carrier": "T-MOBILE USA, INC.", "checked_at": "2026-07-28T17:04:11.000Z", "attested_at": "2026-07-28T17:04:14.000Z" }, "metadata": { "ticket": "4821" }}
{
"error": {
"type": "authentication_error",
"code": "invalid_key",
"audience": "developer",
"message": "The API key is missing, malformed, revoked, or does not match the mode of the resource.",
"advice_code": "do_not_try_again",
"agent_message": null,
"display_message": null,
"agent_action": null,
"doc_url": "https://docs.ringup.dev/api-reference/error-codes#invalid_key",
"request_id": "req_8f3c1d2ab4e9"
}
}
{ "session_status": "complete", "payment_required": "required", "amount_cents": 1650, "currency": "USD", "return_to": "https://example.com/calls/7c2a91e4", "charge": { "charge_id": "chg_77386e2f", "status": "succeeded", "amount_cents": 1650, "processor_payment_id": "pay_9J2mQ7bK4dR", "wallet": null }, "cards": [], "default_card_id": null, "caller_first_name": "Dana", "environment": "live", "processor": "square", "business_name": "Blue Bottle Coffee", "voice": "elevenlabs/eleven_turbo_v2_5:nPczCjzI2devNBz1zQrb", "success_message": "You are all set, thanks for calling!", "failure_message": "That card did not go through, I will text you a link.", "tokenization": { "processor": "square", "public_key": "sq0idp-aB3xY7kLmN2pQ9rS", "location_id": "L7Hns8P2M4Q1R", "environment": "production" }, "checkout_session_id": "cs_test_453b5401286d0f80", "merchant_id": "mch_4f2c9a1b7e3d", "order_id": "8QK4M2XJ", "platform_call_id": "call_7c2a91e4", "caller_phone": "+14155550142", "screen": { "decision": "allow", "reasons": [], "notes": [], "attestation": "A", "ported_recently": false, "port_check": "ok", "line_type": "mobile", "carrier": "T-MOBILE USA, INC.", "checked_at": "2026-07-28T17:04:11.000Z", "attested_at": "2026-07-28T17:04:14.000Z" }, "metadata": { "ticket": "4821" }}
{
"error": {
"type": "authentication_error",
"code": "invalid_key",
"audience": "developer",
"message": "The API key is missing, malformed, revoked, or does not match the mode of the resource.",
"advice_code": "do_not_try_again",
"agent_message": null,
"display_message": null,
"agent_action": null,
"doc_url": "https://docs.ringup.dev/api-reference/error-codes#invalid_key",
"request_id": "req_8f3c1d2ab4e9"
}
}
The caller's first name when they are a known person, so a payment line can greet them the same way the pay page does. Null for a genuinely unknown caller. Identity only: whether a card exists is a separate question answered by cards.
Cards chargeable AT THIS MERCHANT, newest first, the same shape create_checkout returns. Present so a payment line holding only the checkout token can offer the saved card from this read. Empty when no payment is required or the session is already settled or expired.
The environment this session belongs to: the mode of the checkout token used to read it (test or live). It is the single source of truth for a hosted page, which renders its config in this environment rather than re-deriving it, so business_name and tokenization below are always computed here and cannot drift to the wrong environment.
decision is step_up only when a positive bad signal was found: the caller's number was ported or swapped within the last seven days, or the original call's carrier attestation came back C or Failed. Every such cause is listed in reasons. A missing signal is never a cause, so a lookup that errored or timed out lands in notes and leaves the decision allow: an outage upstream must not cost an honest caller their saved card.
Null until anything has resolved. Read it to understand why a caller was sent a link instead of being offered a saved card; never speak any of it to the caller.
The browser-side, PUBLISHABLE tokenization key for this merchant (Square app id + seller location, or Clover PAKMS public key), computed in environment. Null when the processor needs none or the config is incomplete. Same shape as the merchant status endpoint.
The payment line reads these three from this session read, not the checkout token. voice is the merchant's matched TTS descriptor (or null for the default voice); success_message/failure_message are the developer's create_checkout closing lines, spoken by the line at charge success / decline. All null when unset.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Ringup","description":"Identity and payments for voice agents","colors":{"primary":"#2450C8","light":"#6E92EC","dark":"#1B3C9E"},"favicon":"https://mintcdn.com/ringup/WOsImafvm8SdtUi8/favicon.svg?fit=max\u0026auto=format\u0026n=WOsImafvm8SdtUi8\u0026q=85\u0026s=30292695f1bb042fd8c043a2645567ef","api":{"playground":{"display":"interactive"}},"navbar":{"links":[{"href":"https://ringup.dev","label":"ringup.dev"}],"primary":{"type":"button","label":"Log in","href":"https://ringup.dev/login/"}},"footer":{"socials":{"website":"https://ringup.dev"}},"fonts":{"heading":{"family":"Fraunces"},"body":{"family":"Hanken Grotesk"}},"integrations":{"posthog":{"apiKey":"phc_kWiG6vnFemWYbzs9MP6LauRgVVZznuijxYiEmijW2AjM"}},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"ringup","hasAudioNarration":false,"actualSubdomain":"ringup","customDomains":["docs.ringup.dev"],"gitSource":{"type":"github","owner":"atifnayeem-oss","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6ad671f21a30caab2b7f616b","clientVersion":"0.0.4088","searchFilterCounts":[{"language":"default","tag":"Documentation","count":17},{"language":"default","tag":"API reference","count":13},{"language":"default","tag":"Concepts","count":8},{"language":"default","tag":"Tools","count":7},{"language":"default","tag":"API Reference","count":7},{"language":"default","tag":"Get started","count":4},{"language":"default","tag":"Errors","count":3},{"language":"default","tag":"Merchant integrations","count":3},{"language":"default","tag":"Changelog","count":2},{"language":"default","tag":"Developer integrations","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"comment-mode","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/retrieve-a-checkout-session","slug":"/api-reference/retrieve-a-checkout-session","pageMetadata":{"title":"Retrieve a checkout session","description":"Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/checkout_sessions/{checkout_session_id}","href":"/api-reference/retrieve-a-checkout-session","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Retrieve a checkout session","description":"Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/checkout_sessions/{checkout_session_id}","href":"/api-reference/retrieve-a-checkout-session","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"getCheckoutSession","summary":"Retrieve a checkout session","description":"Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge.","security":["6f989058-9147-497e-91c6-b291c82a5588"],"parameters":["4f9d2069-0ab1-475a-af7d-deb1f48ae824"],"responses":{"200":"30b85cfe-7d94-4413-9589-a51437b5927b","401":"e0ac9c07-37fd-4494-80bf-3cc5abbf12b9","404":"d331c345-db3a-425f-88a4-2018a4c37280"},"method":"get","type":"path","servers":["27b78901-71f8-4c6b-9167-a7f12d7c34d6"],"path":"/v1/checkout_sessions/{checkout_session_id}","baseUrlOptions":["https://api.ringup.dev"],"title":"Retrieve a checkout session","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"4f9d2069-0ab1-475a-af7d-deb1f48ae824":{"name":"checkout_session_id","in":"path","required":true,"schema":{"type":"string","isRequired":true,"uniqueKey":"","typeLabel":"string"}}},"responses":{"30b85cfe-7d94-4413-9589-a51437b5927b":{"description":"Success.","content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"amount_cents":{"type":"number","uniqueKey":"amount_cents","typeLabel":"number"},"business_name":{"oneOf":[{"description":"The merchant's own business name for the pay page header, or null (neutral fallback).","type":"string","uniqueKey":"business_name.oneOf.0","typeLabel":"string"},{"description":"The merchant's own business name for the pay page header, or null (neutral fallback).","type":"null","uniqueKey":"business_name.oneOf.1","typeLabel":"null"}],"uniqueKey":"business_name","typeLabel":"string | null"},"caller_first_name":{"oneOf":[{"description":"The caller's first name when they are a known person, so a payment line can greet them the same way the pay page does. Null for a genuinely unknown caller. Identity only: whether a card exists is a separate question answered by `cards`.","type":"string","uniqueKey":"caller_first_name.oneOf.0","typeLabel":"string"},{"description":"The caller's first name when they are a known person, so a payment line can greet them the same way the pay page does. Null for a genuinely unknown caller. Identity only: whether a card exists is a separate question answered by `cards`.","type":"null","uniqueKey":"caller_first_name.oneOf.1","typeLabel":"null"}],"uniqueKey":"caller_first_name","typeLabel":"string | null"},"caller_phone":{"oneOf":[{"description":"The caller's number this session was opened for. Consumers holding only the checkout token (which carries no payload) read it from here.","type":"string","uniqueKey":"caller_phone.oneOf.0","typeLabel":"string"},{"description":"The caller's number this session was opened for. Consumers holding only the checkout token (which carries no payload) read it from here.","type":"null","uniqueKey":"caller_phone.oneOf.1","typeLabel":"null"}],"uniqueKey":"caller_phone","typeLabel":"string | null"},"cards":{"description":"Cards chargeable AT THIS MERCHANT, newest first, the same shape create_checkout returns. Present so a payment line holding only the checkout token can offer the saved card from this read. Empty when no payment is required or the session is already settled or expired.","items":{"additionalProperties":false,"properties":{"brand":{"type":"string","uniqueKey":"cards.items.[INDEX].brand","typeLabel":"string"},"expiry":{"type":"string","uniqueKey":"cards.items.[INDEX].expiry","typeLabel":"string"},"instrument_id":{"description":"The value `charge` requires.","type":"string","uniqueKey":"cards.items.[INDEX].instrument_id","typeLabel":"string"},"last_four":{"type":"string","uniqueKey":"cards.items.[INDEX].last_four","typeLabel":"string"}},"type":"object","uniqueKey":"cards.items.[INDEX]","typeLabel":"object"},"type":"array","uniqueKey":"cards","typeLabel":"object[]"},"charge":{"oneOf":[{"type":"object","properties":{"amount_cents":{"type":"number","uniqueKey":"charge.oneOf.0.amount_cents","typeLabel":"number"},"charge_id":{"type":"string","uniqueKey":"charge.oneOf.0.charge_id","typeLabel":"string"},"processor_payment_id":{"oneOf":[{"type":"string","uniqueKey":"charge.oneOf.0.processor_payment_id.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"charge.oneOf.0.processor_payment_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"charge.oneOf.0.processor_payment_id","typeLabel":"string | null"},"status":{"description":"Where a charge stands.\n\n`pending` means the charge is not settled: the processor has not confirmed an outcome, and it may or may not have taken the payment. Do NOT start another payment for the same order. We resolve it for you and the result arrives on the webhook.\n\n`completed` and `failed` are settled and final.","enum":["pending","succeeded","failed"],"type":"string","uniqueKey":"charge.oneOf.0.status","typeLabel":"enum\u003cstring>"},"wallet":{"oneOf":[{"description":"Which wallet paid (`apple_pay` | `google_pay`), null on a card charge.","enum":["apple_pay","google_pay",null],"type":"string","uniqueKey":"charge.oneOf.0.wallet.oneOf.0","typeLabel":"enum\u003cstring>"},{"description":"Which wallet paid (`apple_pay` | `google_pay`), null on a card charge.","enum":["apple_pay","google_pay",null],"type":"null","uniqueKey":"charge.oneOf.0.wallet.oneOf.1","typeLabel":"null"}],"uniqueKey":"charge.oneOf.0.wallet","typeLabel":"enum\u003cstring> | null"}},"additionalProperties":false,"uniqueKey":"charge.oneOf.0","typeLabel":"object"},{"type":"null","uniqueKey":"charge.oneOf.1","typeLabel":"null"}],"uniqueKey":"charge","typeLabel":"object | null"},"checkout_session_id":{"type":"string","uniqueKey":"checkout_session_id","typeLabel":"string"},"currency":{"type":"string","uniqueKey":"currency","typeLabel":"string"},"default_card_id":{"oneOf":[{"type":"string","uniqueKey":"default_card_id.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"default_card_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"default_card_id","typeLabel":"string | null"},"environment":{"description":"The environment this session belongs to: the mode of the checkout token used to read it (`test` or `live`). It is the single source of truth for a hosted page, which renders its config in this environment rather than re-deriving it, so `business_name` and `tokenization` below are always computed here and cannot drift to the wrong environment.","enum":["test","live"],"type":"string","uniqueKey":"environment","typeLabel":"enum\u003cstring>"},"failure_message":{"oneOf":[{"type":"string","uniqueKey":"failure_message.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"failure_message.oneOf.1","typeLabel":"null"}],"uniqueKey":"failure_message","typeLabel":"string | null"},"merchant_id":{"type":"string","uniqueKey":"merchant_id","typeLabel":"string"},"metadata":{"oneOf":[{"type":"object","additionalProperties":{"type":"string","uniqueKey":"metadata.oneOf.0.additionalProperties","typeLabel":"string"},"uniqueKey":"metadata.oneOf.0","typeLabel":"object"},{"type":"null","uniqueKey":"metadata.oneOf.1","typeLabel":"null"}],"uniqueKey":"metadata","typeLabel":"object | null"},"order_id":{"oneOf":[{"type":"string","uniqueKey":"order_id.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"order_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"order_id","typeLabel":"string | null"},"payment_required":{"enum":["required","optional","none"],"type":"string","uniqueKey":"payment_required","typeLabel":"enum\u003cstring>"},"platform_call_id":{"oneOf":[{"type":"string","uniqueKey":"platform_call_id.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"platform_call_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"platform_call_id","typeLabel":"string | null"},"processor":{"oneOf":[{"description":"The merchant's processor (`square`, `clover`, …), so the pay page builds the right card source without a separate lookup. Null if the merchant is gone.","type":"string","uniqueKey":"processor.oneOf.0","typeLabel":"string"},{"description":"The merchant's processor (`square`, `clover`, …), so the pay page builds the right card source without a separate lookup. Null if the merchant is gone.","type":"null","uniqueKey":"processor.oneOf.1","typeLabel":"null"}],"uniqueKey":"processor","typeLabel":"string | null"},"return_to":{"oneOf":[{"type":"string","uniqueKey":"return_to.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"return_to.oneOf.1","typeLabel":"null"}],"uniqueKey":"return_to","typeLabel":"string | null"},"screen":{"oneOf":[{"type":"object","description":"What screening knows about this caller, and why.\n\n`decision` is `step_up` only when a positive bad signal was found: the caller's number was ported or swapped within the last seven days, or the original call's carrier attestation came back C or Failed. Every such cause is listed in `reasons`. A missing signal is never a cause, so a lookup that errored or timed out lands in `notes` and leaves the decision `allow`: an outage upstream must not cost an honest caller their saved card.\n\nNull until anything has resolved. Read it to understand why a caller was sent a link instead of being offered a saved card; never speak any of it to the caller.","properties":{"attestation":{"oneOf":[{"enum":["A","B","C","F",null],"type":"string","uniqueKey":"screen.oneOf.0.attestation.oneOf.0","typeLabel":"enum\u003cstring>"},{"enum":["A","B","C","F",null],"type":"null","uniqueKey":"screen.oneOf.0.attestation.oneOf.1","typeLabel":"null"}],"uniqueKey":"screen.oneOf.0.attestation","typeLabel":"enum\u003cstring> | null"},"attested_at":{"oneOf":[{"type":"string","uniqueKey":"screen.oneOf.0.attested_at.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"screen.oneOf.0.attested_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"screen.oneOf.0.attested_at","typeLabel":"string | null"},"carrier":{"oneOf":[{"type":"string","uniqueKey":"screen.oneOf.0.carrier.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"screen.oneOf.0.carrier.oneOf.1","typeLabel":"null"}],"uniqueKey":"screen.oneOf.0.carrier","typeLabel":"string | null"},"checked_at":{"oneOf":[{"type":"string","uniqueKey":"screen.oneOf.0.checked_at.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"screen.oneOf.0.checked_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"screen.oneOf.0.checked_at","typeLabel":"string | null"},"decision":{"enum":["allow","step_up"],"type":"string","uniqueKey":"screen.oneOf.0.decision","typeLabel":"enum\u003cstring>"},"line_type":{"oneOf":[{"type":"string","uniqueKey":"screen.oneOf.0.line_type.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"screen.oneOf.0.line_type.oneOf.1","typeLabel":"null"}],"uniqueKey":"screen.oneOf.0.line_type","typeLabel":"string | null"},"notes":{"items":{"type":"string","uniqueKey":"screen.oneOf.0.notes.items.[INDEX]","typeLabel":"string"},"type":"array","uniqueKey":"screen.oneOf.0.notes","typeLabel":"string[]"},"port_check":{"enum":["ok","error","skipped"],"type":"string","uniqueKey":"screen.oneOf.0.port_check","typeLabel":"enum\u003cstring>"},"ported_recently":{"oneOf":[{"type":"boolean","uniqueKey":"screen.oneOf.0.ported_recently.oneOf.0","typeLabel":"boolean"},{"type":"null","uniqueKey":"screen.oneOf.0.ported_recently.oneOf.1","typeLabel":"null"}],"uniqueKey":"screen.oneOf.0.ported_recently","typeLabel":"boolean | null"},"reasons":{"items":{"type":"string","uniqueKey":"screen.oneOf.0.reasons.items.[INDEX]","typeLabel":"string"},"type":"array","uniqueKey":"screen.oneOf.0.reasons","typeLabel":"string[]"}},"additionalProperties":false,"uniqueKey":"screen.oneOf.0","typeLabel":"object"},{"type":"null","description":"What screening knows about this caller, and why.\n\n`decision` is `step_up` only when a positive bad signal was found: the caller's number was ported or swapped within the last seven days, or the original call's carrier attestation came back C or Failed. Every such cause is listed in `reasons`. A missing signal is never a cause, so a lookup that errored or timed out lands in `notes` and leaves the decision `allow`: an outage upstream must not cost an honest caller their saved card.\n\nNull until anything has resolved. Read it to understand why a caller was sent a link instead of being offered a saved card; never speak any of it to the caller.","uniqueKey":"screen.oneOf.1","typeLabel":"null"}],"uniqueKey":"screen","typeLabel":"object | null"},"session_status":{"description":"Named for the object it describes: the CHARGE has its own `status` below.","enum":["open","complete","expired"],"type":"string","uniqueKey":"session_status","typeLabel":"enum\u003cstring>"},"success_message":{"oneOf":[{"type":"string","uniqueKey":"success_message.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"success_message.oneOf.1","typeLabel":"null"}],"uniqueKey":"success_message","typeLabel":"string | null"},"tokenization":{"oneOf":[{"type":"object","description":"The browser-side, PUBLISHABLE tokenization key for this merchant (Square app id + seller location, or Clover PAKMS public key), computed in `environment`. Null when the processor needs none or the config is incomplete. Same shape as the merchant status endpoint.","properties":{"environment":{"enum":["sandbox","production"],"type":"string","uniqueKey":"tokenization.oneOf.0.environment","typeLabel":"enum\u003cstring>"},"location_id":{"oneOf":[{"type":"string","uniqueKey":"tokenization.oneOf.0.location_id.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"tokenization.oneOf.0.location_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"tokenization.oneOf.0.location_id","typeLabel":"string | null"},"processor":{"type":"string","uniqueKey":"tokenization.oneOf.0.processor","typeLabel":"string"},"public_key":{"type":"string","uniqueKey":"tokenization.oneOf.0.public_key","typeLabel":"string"}},"additionalProperties":false,"uniqueKey":"tokenization.oneOf.0","typeLabel":"object"},{"type":"null","description":"The browser-side, PUBLISHABLE tokenization key for this merchant (Square app id + seller location, or Clover PAKMS public key), computed in `environment`. Null when the processor needs none or the config is incomplete. Same shape as the merchant status endpoint.","uniqueKey":"tokenization.oneOf.1","typeLabel":"null"}],"uniqueKey":"tokenization","typeLabel":"object | null"},"voice":{"oneOf":[{"description":"The payment line reads these three from this session read, not the checkout token. `voice` is the merchant's matched TTS descriptor (or null for the default voice); `success_message`/`failure_message` are the developer's create_checkout closing lines, spoken by the line at charge success / decline. All null when unset.","type":"string","uniqueKey":"voice.oneOf.0","typeLabel":"string"},{"description":"The payment line reads these three from this session read, not the checkout token. `voice` is the merchant's matched TTS descriptor (or null for the default voice); `success_message`/`failure_message` are the developer's create_checkout closing lines, spoken by the line at charge success / decline. All null when unset.","type":"null","uniqueKey":"voice.oneOf.1","typeLabel":"null"}],"uniqueKey":"voice","typeLabel":"string | null"}},"type":"object","uniqueKey":"","typeLabel":"object"},"example":{"session_status":"complete","payment_required":"required","amount_cents":1650,"currency":"USD","return_to":"https://example.com/calls/7c2a91e4","charge":{"charge_id":"chg_77386e2f","status":"succeeded","amount_cents":1650,"processor_payment_id":"pay_9J2mQ7bK4dR","wallet":null},"cards":[],"default_card_id":null,"caller_first_name":"Dana","environment":"live","processor":"square","business_name":"Blue Bottle Coffee","voice":"elevenlabs/eleven_turbo_v2_5:nPczCjzI2devNBz1zQrb","success_message":"You are all set, thanks for calling!","failure_message":"That card did not go through, I will text you a link.","tokenization":{"processor":"square","public_key":"sq0idp-aB3xY7kLmN2pQ9rS","location_id":"L7Hns8P2M4Q1R","environment":"production"},"checkout_session_id":"cs_test_453b5401286d0f80","merchant_id":"mch_4f2c9a1b7e3d","order_id":"8QK4M2XJ","platform_call_id":"call_7c2a91e4","caller_phone":"+14155550142","screen":{"decision":"allow","reasons":[],"notes":[],"attestation":"A","ported_recently":false,"port_check":"ok","line_type":"mobile","carrier":"T-MOBILE USA, INC.","checked_at":"2026-07-28T17:04:11.000Z","attested_at":"2026-07-28T17:04:14.000Z"},"metadata":{"ticket":"4821"}},"examples":{"Example":{"title":"Example","value":{"session_status":"complete","payment_required":"required","amount_cents":1650,"currency":"USD","return_to":"https://example.com/calls/7c2a91e4","charge":{"charge_id":"chg_77386e2f","status":"succeeded","amount_cents":1650,"processor_payment_id":"pay_9J2mQ7bK4dR","wallet":null},"cards":[],"default_card_id":null,"caller_first_name":"Dana","environment":"live","processor":"square","business_name":"Blue Bottle Coffee","voice":"elevenlabs/eleven_turbo_v2_5:nPczCjzI2devNBz1zQrb","success_message":"You are all set, thanks for calling!","failure_message":"That card did not go through, I will text you a link.","tokenization":{"processor":"square","public_key":"sq0idp-aB3xY7kLmN2pQ9rS","location_id":"L7Hns8P2M4Q1R","environment":"production"},"checkout_session_id":"cs_test_453b5401286d0f80","merchant_id":"mch_4f2c9a1b7e3d","order_id":"8QK4M2XJ","platform_call_id":"call_7c2a91e4","caller_phone":"+14155550142","screen":{"decision":"allow","reasons":[],"notes":[],"attestation":"A","ported_recently":false,"port_check":"ok","line_type":"mobile","carrier":"T-MOBILE USA, INC.","checked_at":"2026-07-28T17:04:11.000Z","attested_at":"2026-07-28T17:04:14.000Z"},"metadata":{"ticket":"4821"}}}},"exampleType":"examples"}},"exampleType":"examples"},"e0ac9c07-37fd-4494-80bf-3cc5abbf12b9":{"description":"`invalid_key` The API key is missing, malformed, revoked, or does not match the mode of the resource.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"THE error object. Identical on every endpoint: provisioning, identify, checkout, cards, charge. A failed charge (which arrives as a 200 with `status: \"failed\"`) carries the SAME fields under `failure`, so a developer writes one parser and it works everywhere.","properties":{"error":{"additionalProperties":false,"properties":{"advice_code":{"description":"try_again_later | confirm_card_data | do_not_try_again","enum":["try_again_later","do_not_try_again","confirm_card_data"],"type":"string","uniqueKey":"error.advice_code","typeLabel":"enum\u003cstring>"},"agent_action":{"oneOf":[{"type":"string","description":"Null on every `developer`-audience error: see agent_message.","enum":["retry_card","offer_different_card","send_link","end_call","escalate"],"uniqueKey":"error.agent_action.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","description":"Null on every `developer`-audience error: see agent_message.","uniqueKey":"error.agent_action.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.agent_action","typeLabel":"enum\u003cstring> | null"},"agent_message":{"oneOf":[{"description":"Speak verbatim WHEN NON-NULL. Null on every `developer`-audience error.","type":"string","uniqueKey":"error.agent_message.oneOf.0","typeLabel":"string"},{"description":"Speak verbatim WHEN NON-NULL. Null on every `developer`-audience error.","type":"null","uniqueKey":"error.agent_message.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.agent_message","typeLabel":"string | null"},"audience":{"description":"Who this error is for. Drives whether there is anything to speak at all.","enum":["developer","caller"],"type":"string","uniqueKey":"error.audience","typeLabel":"enum\u003cstring>"},"charge":{"description":"Present when the error concerns a specific charge.","type":"string","uniqueKey":"error.charge","typeLabel":"string"},"code":{"enum":["invalid_json","missing_required_fields","invalid_value","invalid_key","vendor_not_provisioned","merchant_not_found","merchant_not_connected","invalid_processor","invalid_credentials","invalid_payment_policy","invalid_payment_policy_amount_cents","session_not_found","session_expired","session_create_failed","session_missing_consumer","missing_checkout_session_id","order_lookup_failed","order_lookup_unsupported","instrument_not_found","instrument_not_authorized","card_not_on_file","missing_instrument_fields","processor_mismatch","needs_enrollment","charge_details_mismatch","card_save_failed","card_declined","processor_unavailable","merchant_credentials_invalid","invalid_vault","key_not_found","invalid_environment","invalid_url","invalid_events","invalid_ttl","invalid_state_key","not_found","not_configured","rate_limit","internal_error"],"type":"string","uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"decline_code":{"type":"string","uniqueKey":"error.decline_code","typeLabel":"string"},"display_message":{"oneOf":[{"description":"The same fact written for a screen. Null on `developer`-audience errors.","type":"string","uniqueKey":"error.display_message.oneOf.0","typeLabel":"string"},{"description":"The same fact written for a screen. Null on `developer`-audience errors.","type":"null","uniqueKey":"error.display_message.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.display_message","typeLabel":"string | null"},"doc_url":{"type":"string","uniqueKey":"error.doc_url","typeLabel":"string"},"message":{"type":"string","uniqueKey":"error.message","typeLabel":"string"},"param":{"type":"string","uniqueKey":"error.param","typeLabel":"string"},"processor_code":{"type":"string","uniqueKey":"error.processor_code","typeLabel":"string"},"request_id":{"type":"string","uniqueKey":"error.request_id","typeLabel":"string"},"request_log_url":{"description":"Deep link to this request in the dashboard. Present once the dashboard log view exists.","type":"string","uniqueKey":"error.request_log_url","typeLabel":"string"},"type":{"enum":["invalid_request_error","authentication_error","permission_error","card_error","processor_error","idempotency_error","rate_limit_error","api_error"],"type":"string","uniqueKey":"error.type","typeLabel":"enum\u003cstring>"}},"type":"object","uniqueKey":"error","typeLabel":"object"}},"type":"object","uniqueKey":"","typeLabel":"object"},"examples":{"invalid_key":{"title":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","audience":"developer","message":"The API key is missing, malformed, revoked, or does not match the mode of the resource.","advice_code":"do_not_try_again","agent_message":null,"display_message":null,"agent_action":null,"doc_url":"https://docs.ringup.dev/api-reference/error-codes#invalid_key","request_id":"req_8f3c1d2ab4e9"}}}},"exampleType":"examples"}},"exampleType":"examples"},"d331c345-db3a-425f-88a4-2018a4c37280":{"description":"`not_found` No route matches this path and method.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"THE error object. Identical on every endpoint: provisioning, identify, checkout, cards, charge. A failed charge (which arrives as a 200 with `status: \"failed\"`) carries the SAME fields under `failure`, so a developer writes one parser and it works everywhere.","properties":{"error":{"additionalProperties":false,"properties":{"advice_code":{"description":"try_again_later | confirm_card_data | do_not_try_again","enum":["try_again_later","do_not_try_again","confirm_card_data"],"type":"string","uniqueKey":"error.advice_code","typeLabel":"enum\u003cstring>"},"agent_action":{"oneOf":[{"type":"string","description":"Null on every `developer`-audience error: see agent_message.","enum":["retry_card","offer_different_card","send_link","end_call","escalate"],"uniqueKey":"error.agent_action.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","description":"Null on every `developer`-audience error: see agent_message.","uniqueKey":"error.agent_action.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.agent_action","typeLabel":"enum\u003cstring> | null"},"agent_message":{"oneOf":[{"description":"Speak verbatim WHEN NON-NULL. Null on every `developer`-audience error.","type":"string","uniqueKey":"error.agent_message.oneOf.0","typeLabel":"string"},{"description":"Speak verbatim WHEN NON-NULL. Null on every `developer`-audience error.","type":"null","uniqueKey":"error.agent_message.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.agent_message","typeLabel":"string | null"},"audience":{"description":"Who this error is for. Drives whether there is anything to speak at all.","enum":["developer","caller"],"type":"string","uniqueKey":"error.audience","typeLabel":"enum\u003cstring>"},"charge":{"description":"Present when the error concerns a specific charge.","type":"string","uniqueKey":"error.charge","typeLabel":"string"},"code":{"enum":["invalid_json","missing_required_fields","invalid_value","invalid_key","vendor_not_provisioned","merchant_not_found","merchant_not_connected","invalid_processor","invalid_credentials","invalid_payment_policy","invalid_payment_policy_amount_cents","session_not_found","session_expired","session_create_failed","session_missing_consumer","missing_checkout_session_id","order_lookup_failed","order_lookup_unsupported","instrument_not_found","instrument_not_authorized","card_not_on_file","missing_instrument_fields","processor_mismatch","needs_enrollment","charge_details_mismatch","card_save_failed","card_declined","processor_unavailable","merchant_credentials_invalid","invalid_vault","key_not_found","invalid_environment","invalid_url","invalid_events","invalid_ttl","invalid_state_key","not_found","not_configured","rate_limit","internal_error"],"type":"string","uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"decline_code":{"type":"string","uniqueKey":"error.decline_code","typeLabel":"string"},"display_message":{"oneOf":[{"description":"The same fact written for a screen. Null on `developer`-audience errors.","type":"string","uniqueKey":"error.display_message.oneOf.0","typeLabel":"string"},{"description":"The same fact written for a screen. Null on `developer`-audience errors.","type":"null","uniqueKey":"error.display_message.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.display_message","typeLabel":"string | null"},"doc_url":{"type":"string","uniqueKey":"error.doc_url","typeLabel":"string"},"message":{"type":"string","uniqueKey":"error.message","typeLabel":"string"},"param":{"type":"string","uniqueKey":"error.param","typeLabel":"string"},"processor_code":{"type":"string","uniqueKey":"error.processor_code","typeLabel":"string"},"request_id":{"type":"string","uniqueKey":"error.request_id","typeLabel":"string"},"request_log_url":{"description":"Deep link to this request in the dashboard. Present once the dashboard log view exists.","type":"string","uniqueKey":"error.request_log_url","typeLabel":"string"},"type":{"enum":["invalid_request_error","authentication_error","permission_error","card_error","processor_error","idempotency_error","rate_limit_error","api_error"],"type":"string","uniqueKey":"error.type","typeLabel":"enum\u003cstring>"}},"type":"object","uniqueKey":"error","typeLabel":"object"}},"type":"object","uniqueKey":"","typeLabel":"object"},"examples":{"not_found":{"title":"not_found","value":{"error":{"type":"invalid_request_error","code":"not_found","audience":"developer","message":"No route matches this path and method.","advice_code":"do_not_try_again","agent_message":null,"display_message":null,"agent_action":null,"doc_url":"https://docs.ringup.dev/api-reference/error-codes#not_found","request_id":"req_8f3c1d2ab4e9"}}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"6f989058-9147-497e-91c6-b291c82a5588":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"rk_live_…","scopes":[],"schemeName":"bearerAuth"}}},"servers":{"27b78901-71f8-4c6b-9167-a7f12d7c34d6":{"url":"https://api.ringup.dev"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","bearerFormat":"rk_live_…","scopes":[],"schemeName":"bearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Bearer authentication header of the form `Bearer \u003ctoken>`, where `\u003ctoken>` is your auth token.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"ringup","siteName":"Ringup","title":"Retrieve a checkout session - Ringup","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-19T19:39:33.718Z","originalFileLocation":"api-reference/retrieve-a-checkout-session.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Ringup\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/ringup/T7qfQGwQEgu8hb1T/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/ringup/T7qfQGwQEgu8hb1T/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/ringup/T7qfQGwQEgu8hb1T/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/ringup/T7qfQGwQEgu8hb1T/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/ringup/T7qfQGwQEgu8hb1T/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/ringup/T7qfQGwQEgu8hb1T/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/ringup/T7qfQGwQEgu8hb1T/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/ringup/T7qfQGwQEgu8hb1T/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/ringup/T7qfQGwQEgu8hb1T/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Retrieve a checkout session - Ringup\">\u003cmeta data-mint-head property=\"og:description\" content=\"Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Ringup\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.ringup.dev/api-reference/retrieve-a-checkout-session\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://ringup.mintlify.site/_mintlify/api/og/v2?division=API+Reference\u0026amp;title=Retrieve+a+checkout+session\u0026amp;description=Read+a+session+and+its+charge.+A+lookup%2C+so+a+decline+reads+as+200+with+a+failed+charge.\u0026amp;theme=b118f4e35f9b7ec55672e6b7\u0026amp;signature=e3101cef0d8008fe0340d1d0a003c4188723e771b01c1e66750a08d8f15f8dfd\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Retrieve a checkout session - Ringup\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://ringup.mintlify.site/_mintlify/api/og/v2?division=API+Reference\u0026amp;title=Retrieve+a+checkout+session\u0026amp;description=Read+a+session+and+its+charge.+A+lookup%2C+so+a+decline+reads+as+200+with+a+failed+charge.\u0026amp;theme=b118f4e35f9b7ec55672e6b7\u0026amp;signature=e3101cef0d8008fe0340d1d0a003c4188723e771b01c1e66750a08d8f15f8dfd\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/ringup/T7qfQGwQEgu8hb1T/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Ringup\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2450C8\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.ringup.dev/api-reference/retrieve-a-checkout-session\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/retrieve-a-checkout-session.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.ringup.dev/#organization\",\"name\":\"Ringup\",\"url\":\"https://docs.ringup.dev\"},{\"@type\":\"WebSite\",\"@id\":\"https://docs.ringup.dev#website\",\"name\":\"Ringup\",\"url\":\"https://docs.ringup.dev\",\"publisher\":{\"@id\":\"https://docs.ringup.dev/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.ringup.dev/api-reference/retrieve-a-checkout-session#webpage\",\"url\":\"https://docs.ringup.dev/api-reference/retrieve-a-checkout-session\",\"name\":\"Retrieve a checkout session\",\"description\":\"Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge.\",\"dateModified\":\"2026-10-19T19:39:33.718Z\",\"isPartOf\":{\"@id\":\"https://docs.ringup.dev#website\"},\"breadcrumb\":{\"@id\":\"https://docs.ringup.dev/api-reference/retrieve-a-checkout-session#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.ringup.dev/api-reference/retrieve-a-checkout-session#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Tools\",\"item\":\"https://docs.ringup.dev/api-reference/recognize-a-caller\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"API Reference\",\"item\":\"https://docs.ringup.dev/api-reference/recognize-a-caller\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Retrieve a checkout session\",\"item\":\"https://docs.ringup.dev/api-reference/retrieve-a-checkout-session\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.ringup.dev/api-reference/retrieve-a-checkout-session#apireference\",\"headline\":\"Retrieve a checkout session\",\"name\":\"Retrieve a checkout session\",\"description\":\"Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge.\",\"url\":\"https://docs.ringup.dev/api-reference/retrieve-a-checkout-session\",\"mainEntityOfPage\":{\"@id\":\"https://docs.ringup.dev/api-reference/retrieve-a-checkout-session#webpage\"},\"dateModified\":\"2026-10-19T19:39:33.718Z\",\"publisher\":{\"@id\":\"https://docs.ringup.dev/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.ringup.dev#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Ringup\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Ringup","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":""}]},{"tab":"API reference","groups":[{"group":"API reference","pages":[{"title":"Introduction","href":"/api-reference/introduction"}]},{"group":"Tools","pages":[{"group":"API Reference","pages":[{"title":"Recognize a caller","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/identify","href":"/api-reference/recognize-a-caller"},{"title":"Create a checkout session","description":"Resolve the amount, apply the merchant's payment policy, and return the transfer target when payment is required.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/create_checkout","href":"/api-reference/create-a-checkout-session"},{"title":"Retrieve a checkout session","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/checkout_sessions/{checkout_session_id}","href":"/api-reference/retrieve-a-checkout-session"},{"title":"Charge a saved card","description":"Charge the card the caller chose against an open Checkout Session. A decline is a 402 in the standard error envelope, not a 200 result.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/charge","href":"/api-reference/charge-a-saved-card"},{"title":"Send a pay link","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/send_link","href":"/api-reference/send-a-pay-link"},{"title":"List webhook endpoints","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/webhook_endpoints","href":"/api-reference/list-webhook-endpoints"},{"title":"Create a webhook endpoint","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/webhook_endpoints","href":"/api-reference/create-a-webhook-endpoint"}]}]},{"group":"Events","pages":[{"title":"Events","href":"/api-reference/events"}]},{"group":"Errors","pages":[{"title":"Errors","href":"/api-reference/errors"},{"title":"Error codes","href":"/api-reference/error-codes"},{"title":"Handling errors","href":"/api-reference/handling-errors"}]}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]}]},"basePath":"","title":"Retrieve a checkout session - Ringup","buildId":"dpl_DTau1J5HqS9UTgVSDwGksstFWtPa","deploymentId":"dpl_DTau1J5HqS9UTgVSDwGksstFWtPa","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-5FCzAcfS.js","utils-SLtAG4EZ.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-2DZi8ZMu.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-D7J3nkzE.js","snippetPresets-D0Alv0AH.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-BI4qNJ2c.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-BD3uyr8j.js","shallow-D8iEBr5z.js","getApiPlaygroundDisplay-CgNP4lzR.js","CodeSnippet-CX-QHuMs.js","CodeSnippets-VlXE-ZUf.js","Page-D9ithiIZ.js","getPastedJson-DYNQkZ1M.js","icon-CzacdwOi.js","MethodPill-2JVqoYKi.js","DuplicateIcon-_xVXs-U8.js","createIcon-BRHrweLo.js","DynamicMarkdown-mQG_iQiE.js","SectionHeading-DMpJzv8f.js","axios-vUo_bRtp.js","Markdown-5FGIym-8.js","clsx-D-TRO5q5.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-CdrJecqK.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-CHlcWBLM.js"]}