> ## Documentation Index > Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a checkout session > Returns a checkout session. For a payment, check both `status == "complete"` and `payment_status == "paid"` before showing a confirmed result. Fulfill from the verified completion webhook; a redirect or SDK callback alone is not confirmation. Secrets (`client_secret`, `payment_intent_client_secret`) are stripped. ## OpenAPI ````yaml /openapi/checkout.yaml get /checkout/sessions/{id} openapi: 3.0.3 info: title: Ionic Checkout API version: '2026-05-01' description: > Checkout sessions — hosted and embedded payment collection with PCI compliance built in. A checkout session (`cs_…`) represents one buyer attempt to make a one-time payment or activate a subscription. Create it on your server with line items and optional redirect URLs; the buyer completes the form on the hosted page or in an embedded iframe; your server verifies completion by retrieving the session and processing webhook events. **Session lifecycle:** A session starts `open`. A payment-mode session moves to `complete` once its one-time payment succeeds. A subscription-mode session moves to `complete` once hosted checkout creates and activates the subscription. Either mode becomes `expired` if not completed before `expires_at` (default 24 hours). **Integration modes:** Hosted checkout (`ui_mode: hosted`) redirects the buyer to `checkout.ionicfi.com`; the session response includes a `url` to redirect to. Embedded checkout (`ui_mode: embedded`) mounts an iframe on your domain via the `@ionicfi/js` SDK; the session response includes a `client_secret` to pass to the SDK. Embedded mode is in preview and requires domain allowlisting. **Line items:** For one-time payments, use `price_id` to reference a one-time catalog price (recommended) or supply `name`, `amount`, and `currency` inline for a dynamic amount. Subscription sessions require recurring catalog prices. All items in one session must share the same currency; recurring items must also share one cadence. Amounts are integers in the currency's minor unit (for example, cents for USD). Timestamps are Unix epoch seconds. **Authentication:** Write endpoints require `sessions:write`; read endpoints require `sessions:read`. The mode of the key (test or live) scopes which sessions it can see and mutate, reflected by each session's `livemode` field. Send an `Idempotency-Key` header on `POST /checkout/sessions` and `POST /checkout/sessions/{id}/confirm` so a retried request never creates a duplicate session or a duplicate payment intent. Errors are returned as `{ "error": { "code": "...", "message": "..." } }`. servers: - url: '{baseUrl}/v1' variables: baseUrl: default: https://api.ionicfi.com description: API base URL for your environment. security: - secretKey: [] tags: - name: Checkout Sessions description: Create, retrieve, list, confirm, and mutate checkout sessions. paths: /checkout/sessions/{id}: parameters: - $ref: '#/components/parameters/CheckoutSessionId' get: tags: - Checkout Sessions summary: Retrieve a checkout session description: > Returns a checkout session. For a payment, check both `status == "complete"` and `payment_status == "paid"` before showing a confirmed result. Fulfill from the verified completion webhook; a redirect or SDK callback alone is not confirmation. Secrets (`client_secret`, `payment_intent_client_secret`) are stripped. operationId: checkout_sessions_retrieve responses: '200': description: The checkout session. content: application/json: schema: $ref: '#/components/schemas/CheckoutSession' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/CheckoutSessionNotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - sessions:read components: parameters: CheckoutSessionId: name: id in: path required: true description: The checkout session id (`cs_…`). schema: type: string schemas: CheckoutSession: type: object description: A checkout session. required: - id - object - merchant_id - livemode - mode - ui_mode - status - payment_status - line_items - amount_subtotal - amount_total - currency - expires_at - metadata - created_at - updated_at - cancel_url - client_reference_id - collect_config - customer - customer_email - locale - payment_intent_id - submit_type - success_url properties: id: type: string description: Checkout session id (`cs_…`). object: type: string enum: - checkout_session merchant_id: type: string description: Merchant id that owns this session (`mer_…`). merchant: nullable: true allOf: - $ref: '#/components/schemas/MerchantDisplay' description: >- Merchant display details. Present when the session was retrieved from the hosted checkout page context. livemode: type: boolean description: True for live-mode sessions; false for test-mode. mode: type: string enum: - payment - subscription - setup description: Checkout mode. ui_mode: type: string enum: - hosted - embedded description: Presentation mode. submit_type: type: string enum: - auto - pay - book - donate description: Checkout button label mode. status: type: string enum: - open - complete - expired description: >- `open` — active, buyer can continue. `complete` — the hosted payment or subscription activation finished; inspect `payment_status` and process webhooks. `expired` — timed out, buyer must start a new session. payment_status: type: string enum: - paid - unpaid - no_payment_required description: Payment outcome. client_secret: type: string description: >- SDK initialization token for embedded mode. Present only on the create response when `ui_mode` is `embedded`; absent on all other responses. success_url: type: string nullable: true description: URL to redirect the buyer after successful payment. cancel_url: type: string nullable: true description: URL to redirect the buyer if they cancel. locale: type: string nullable: true description: Checkout page locale. customer: type: string nullable: true description: Linked customer id (`cus_…`). customer_email: type: string nullable: true description: Pre-filled email address. client_reference_id: type: string nullable: true description: Merchant-supplied reference id. line_items: type: array items: $ref: '#/components/schemas/LineItem' description: Required line items. optional_items: type: array items: $ref: '#/components/schemas/LineItem' description: >- Optional upsell items offered on the checkout form. Absent when none were configured. selected_optional_item_ids: type: array items: type: string description: >- Ids of optional items the buyer selected. Absent when none are selected. collect_config: allOf: - $ref: '#/components/schemas/CollectConfig' description: Field-collection requirements for this session. amount_subtotal: type: integer format: int64 description: Sum of required line item amounts in minor units. amount_total: type: integer format: int64 description: Subtotal plus the amounts of selected optional items in minor units. currency: type: string description: >- Uppercase three-letter ISO currency code, derived from the first line item. payment_intent_id: type: string nullable: true description: >- The payment intent created to collect this session (`pi_…`). Null until the session is confirmed. payment_intent_client_secret: type: string nullable: true description: >- Payment intent client secret. Present only on the confirm response so the frontend can initialize the card form. setup_future_usage: type: string nullable: true enum: - on_session - off_session description: >- Set when the merchant enabled saving the payment method. The hosted form shows a save-card checkbox to the buyer. payment_error: nullable: true allOf: - $ref: '#/components/schemas/PaymentErrorDetail' description: >- Error returned to the buyer surface after a declined charge attempt. Absent when no decline occurred. payment_link_id: type: string nullable: true description: >- Back-reference to the payment link that spawned this session (`pl_…`). Absent for API-created sessions. expires_at: type: integer format: int64 description: Unix epoch seconds when this session expires. tokenization: nullable: true allOf: - $ref: '#/components/schemas/Tokenization' description: >- Card-fields configuration used by Ionic Checkout. Present when the session includes browser tokenization access. provider: nullable: true allOf: - $ref: '#/components/schemas/Provider' description: >- Card-fields configuration used by Ionic Checkout. No integration action is required. url: type: string description: >- Hosted checkout URL (`ui_mode: hosted` only). Redirect the buyer here to begin payment. embed_url: type: string description: 'Embedded checkout iframe URL (`ui_mode: embedded` only).' metadata: type: object additionalProperties: type: string description: Custom key-value pairs attached to this session. created_at: type: integer format: int64 description: Unix epoch seconds. updated_at: type: integer format: int64 MerchantDisplay: type: object description: Merchant display details embedded in a checkout session. properties: name: type: string description: Merchant business name. LineItem: type: object description: A line item on a checkout session. required: - amount - currency - fulfillment_type - id - name - quantity - tip_eligible properties: id: type: string name: type: string amount: type: integer format: int64 description: Unit price in minor units. currency: type: string quantity: type: integer fulfillment_type: type: string enum: - digital - service - shipping - pickup tip_eligible: type: boolean metadata: type: object additionalProperties: type: string description: Custom data for this line item. Absent when empty. price_id: type: string nullable: true description: Catalog price id, or null for inline items. product_id: type: string nullable: true description: Catalog product id. recurring: nullable: true allOf: - $ref: '#/components/schemas/RecurringSchedule' description: >- Recurrence details for subscription-price line items. Absent for one-time prices. adjustable_quantity: nullable: true allOf: - $ref: '#/components/schemas/AdjustableQuantityResult' description: >- Adjustable quantity configuration. Absent when the line item quantity is fixed. image_url: type: string nullable: true description: Snapshotted product image URL captured at session creation. CollectConfig: type: object description: Field-collection requirements for the checkout form. required: - address - email - name - phone - require_full_billing_address - require_phone - require_shipping_address - wallet_billing_mode properties: email: type: string enum: - required - optional - hidden name: type: string enum: - required - optional - hidden phone: type: string enum: - required - optional - hidden address: type: string enum: - required - optional - hidden require_full_billing_address: type: boolean require_shipping_address: type: boolean require_phone: type: boolean wallet_billing_mode: type: string enum: - min - full description: >- How much billing information wallet methods collect. `min` = country and postal code; `full` = complete billing address. PaymentErrorDetail: type: object description: >- Error detail embedded in a checkout session when a charge attempt is declined. required: - code - message properties: code: type: string description: A stable, machine-readable error code. message: type: string type: type: string enum: - card_error - invalid_request_error - api_error decline_code: type: string description: Machine-readable decline reason (e.g., `insufficient_funds`). decline_type: type: string enum: - authorization - authentication - infrastructure retryable: type: boolean description: Whether the buyer can retry with a different card. doc_url: type: string Tokenization: type: object description: Browser-safe card-fields configuration used by Ionic Checkout. properties: provider: type: string description: >- Reserved for the Ionic browser SDK. Do not inspect or configure this value. tokenization_key: type: string description: >- Browser-safe public key used to initialize card fields and create a one-time payment token. Provider: type: object description: >- Browser-safe card-fields setup used by Ionic Checkout. No integration action is required. properties: name: type: string description: Reserved for the Ionic browser SDK. public_key: type: string description: Browser-safe public key for card-fields initialization. config: type: object additionalProperties: true description: Additional browser initialization settings. Error: type: object properties: error: type: object properties: code: type: string description: A stable, machine-readable error code. message: type: string RecurringSchedule: type: object description: Recurrence schedule snapshotted from a subscription price. required: - interval - interval_count properties: interval: type: string description: Billing interval (e.g., `month`, `year`, `week`). interval_count: type: integer description: Number of intervals between billings. AdjustableQuantityResult: type: object description: Adjustable quantity configuration on a line item response. required: - enabled - maximum - minimum properties: enabled: type: boolean minimum: type: integer maximum: type: integer responses: BadRequest: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_REQUEST message: line_items must not be empty Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The key lacks the required permission, or the merchant is not active. content: application/json: schema: $ref: '#/components/schemas/Error' CheckoutSessionNotFound: description: No checkout session with that id is visible to this key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CHECKOUT_SESSION_NOT_FOUND message: checkout session not found RateLimited: description: Too many requests. Honour the `Retry-After` header before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: | The API could not return a successful response. For a mutating request, retrieve the resource before retrying because the operation may have completed. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: secretKey: type: http scheme: bearer description: 'A merchant secret key (`sk_…`) sent as `Authorization: Bearer `.' ````