> ## Documentation Index > Fetch the complete documentation index at: https://docs.ringup.dev/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a checkout session > Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/checkout_sessions/{checkout_session_id} openapi: 3.1.0 info: title: Ringup API version: v1 description: >- Take a card payment on a phone call. Every endpoint is authenticated with a Bearer API key; the key prefix (`rk_test_` / `rk_live_`) selects the environment. servers: - url: https://api.ringup.dev security: [] paths: /v1/checkout_sessions/{checkout_session_id}: get: summary: Retrieve a checkout session description: >- Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge. operationId: getCheckoutSession parameters: - name: checkout_session_id in: path required: true schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/CheckoutSessionResponse' 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' '401': description: >- `invalid_key` The API key is missing, malformed, revoked, or does not match the mode of the resource. content: application/json: schema: $ref: '#/components/schemas/ApiErrorBody' examples: invalid_key: summary: >- The API key is missing, malformed, revoked, or does not match the mode of the resource. 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 '404': description: '`not_found` No route matches this path and method.' content: application/json: schema: $ref: '#/components/schemas/ApiErrorBody' examples: not_found: summary: No route matches this path and method. 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 security: - bearerAuth: [] components: schemas: CheckoutSessionResponse: additionalProperties: false properties: amount_cents: type: number business_name: description: >- The merchant's own business name for the pay page header, or null (neutral fallback). type: - string - 'null' caller_first_name: 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 - 'null' caller_phone: 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 - '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: $ref: '#/components/schemas/SavedCard' type: array charge: anyOf: - additionalProperties: false properties: amount_cents: type: number charge_id: type: string processor_payment_id: type: - string - 'null' status: $ref: '#/components/schemas/ChargeStatus' wallet: description: >- Which wallet paid (`apple_pay` | `google_pay`), null on a card charge. enum: - apple_pay - google_pay - null type: - string - 'null' type: object - type: 'null' checkout_session_id: type: string currency: type: string default_card_id: type: - 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 failure_message: type: - string - 'null' merchant_id: type: string metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' order_id: type: - string - 'null' payment_required: $ref: '#/components/schemas/PaymentRequired' platform_call_id: type: - string - 'null' processor: 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 - 'null' return_to: type: - string - 'null' screen: anyOf: - additionalProperties: false properties: attestation: enum: - A - B - C - F - null type: - string - 'null' attested_at: type: - string - 'null' carrier: type: - string - 'null' checked_at: type: - string - 'null' decision: enum: - allow - step_up type: string line_type: type: - string - 'null' notes: items: type: string type: array port_check: enum: - ok - error - skipped type: string ported_recently: type: - boolean - 'null' reasons: items: type: string type: array type: object - type: 'null' description: >- What screening knows about this caller, and why. `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. session_status: description: >- Named for the object it describes: the CHARGE has its own `status` below. enum: - open - complete - expired type: string success_message: type: - string - 'null' tokenization: anyOf: - additionalProperties: false properties: environment: enum: - sandbox - production type: string location_id: type: - string - 'null' processor: type: string public_key: type: string type: 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. voice: 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 - 'null' type: object ApiErrorBody: 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: $ref: '#/components/schemas/AdviceCode' description: try_again_later | confirm_card_data | do_not_try_again agent_action: anyOf: - $ref: '#/components/schemas/AgentAction' - type: 'null' description: 'Null on every `developer`-audience error: see agent_message.' agent_message: description: >- Speak verbatim WHEN NON-NULL. Null on every `developer`-audience error. type: - string - 'null' audience: $ref: '#/components/schemas/Audience' description: >- Who this error is for. Drives whether there is anything to speak at all. charge: description: Present when the error concerns a specific charge. type: string code: $ref: '#/components/schemas/ErrorCode' decline_code: type: string display_message: description: >- The same fact written for a screen. Null on `developer`-audience errors. type: - string - 'null' doc_url: type: string message: type: string param: type: string processor_code: type: string request_id: type: string request_log_url: description: >- Deep link to this request in the dashboard. Present once the dashboard log view exists. type: string type: $ref: '#/components/schemas/ErrorType' type: object type: object SavedCard: additionalProperties: false properties: brand: type: string expiry: type: string instrument_id: description: The value `charge` requires. type: string last_four: type: string type: object ChargeStatus: description: >- Where a charge stands. `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. `completed` and `failed` are settled and final. enum: - pending - succeeded - failed type: string PaymentRequired: enum: - required - optional - none type: string AdviceCode: description: >- `advice_code` is our guidance to the developer on what to do with this decline programmatically. It is distinct from `agent_action`, which drives the conversation. A decline can be "do not retry this card" (advice) while still being "offer a different card" (agent action). enum: - try_again_later - do_not_try_again - confirm_card_data type: string AgentAction: description: >- What the agent should DO next. Keeps conversational branching deterministic too. enum: - retry_card - offer_different_card - send_link - end_call - escalate type: string Audience: description: >- Who an error is for. `caller` errors are things the person on the phone is living through, so they carry copy your agent can speak. `developer` errors are your integration's own bugs, and carry NO speakable copy at all: the fields are null rather than a neutral filler, because a filler sentence invites an agent to raise payment when nothing about payment has failed. enum: - developer - caller type: string ErrorCode: 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 - 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 ErrorType: enum: - invalid_request_error - authentication_error - permission_error - card_error - processor_error - idempotency_error - rate_limit_error - api_error type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: rk_live_… ````