> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Checkout Session

> Creates a payment provider Checkout session with embedded, hosted, or elements UI, supporting payment, setup, or subscription modes. A subscription session may carry both recurring and one-time prices in one cart and accepts an optional trial.



## OpenAPI

````yaml /openapi.json post /checkouts/sessions
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /checkouts/sessions:
    post:
      tags:
        - Checkout
      summary: Create Checkout Session
      description: >-
        Creates a payment provider Checkout session with embedded, hosted, or
        elements UI, supporting payment, setup, or subscription modes. A
        subscription session may carry both recurring and one-time prices in one
        cart and accepts an optional trial.
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
          description: >-
            Forwarded as the payment provider's request idempotency key. Retried
            requests with the same key and parameters are deduped by the
            provider (roughly a 24-hour replay window) instead of creating a
            second resource. Recommended: an opaque, randomly-generated value
            such as a UUID rather than a predictable or derived string.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ui_mode:
                  type: string
                  description: >-
                    One of `"embedded"`, `"hosted"`, `"embedded_page"`,
                    `"hosted_page"`, `"elements"`. Default `"embedded"`. The
                    legacy `"embedded"`/`"hosted"` values are translated to the
                    payment provider's current values
                    `"embedded_page"`/`"hosted_page"` before the provider call;
                    `"elements"` passes through unchanged; the response echoes
                    the value you sent.
                success_url:
                  type: string
                  description: >-
                    Required when `ui_mode` resolves to a hosted page
                    (`"hosted"` or `"hosted_page"`). Must be a well-formed
                    `http(s)` URL — a malformed value or another scheme is
                    rejected with a `400` rather than forwarded to the provider.
                return_url:
                  type: string
                  description: >-
                    Redirect target after completion for embedded checkouts,
                    where it is optional. Required when `ui_mode` is
                    `"elements"` — the payment provider rejects the session
                    otherwise. Same `http(s)` URL check as `success_url`.
                cancel_url:
                  type: string
                  description: >-
                    Only allowed when `ui_mode` resolves to a hosted page. Shows
                    a back button on the hosted checkout page and redirects the
                    customer here if they cancel. A non-empty value on
                    `"embedded"`, `"embedded_page"` or `"elements"` — including
                    when `ui_mode` is omitted, which defaults to embedded — is
                    rejected with a `400`; a whitespace-only value is treated as
                    absent. Same `http(s)` URL check as `success_url`.
                type:
                  type: string
                  description: 'Session mode: `"payment"`, `"setup"`, or `"subscription"`.'
                customer_data:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Customer name.
                    email:
                      type: string
                      description: >-
                        Customer email; normalized to lowercase and trimmed
                        server-side before the provider call. Must be a valid
                        address of at most 512 characters. Plus addressing
                        (`name+tag@example.com`) is supported.
                    phone:
                      type: string
                      description: Phone number.
                    metadata:
                      type: object
                      description: Custom metadata.
                  description: >-
                    Customer name and email; omit if `provider_customer_id`
                    provided.
                provider_customer_id:
                  type: string
                  description: Existing payment provider customer ID.
                currency:
                  type: string
                  description: Required when `type` is `"setup"`; ISO 4217 code.
                provider_coupon_ids:
                  type: array
                  items:
                    type: string
                  description: >-
                    Coupon IDs; only for payment and subscription modes.
                    Mutually exclusive with `provider_promotion_code_ids`.
                provider_promotion_code_ids:
                  type: array
                  items:
                    type: string
                  description: >-
                    Promotion code IDs; only for payment and subscription modes.
                    Mutually exclusive with `provider_coupon_ids` — providing
                    both is rejected with a `400`.
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/CartItem'
                  description: >-
                    Required for payment and subscription modes. A subscription
                    cart may hold both recurring and one-time prices in one
                    array — no discriminator is needed, each entry is routed by
                    the price's own type, and a one-time amount lands on the
                    subscription's first invoice, charged in full at creation. A
                    subscription cart needs exactly one recurring price, with
                    any number of one-time prices beside it: pause, resume and
                    cancel act on the whole subscription, so create one
                    subscription per recurring product. In a cart of two or more
                    lines, a price unknown to your account is a `404` naming the
                    id; in a one-line cart the payment provider rejects it at
                    session creation.
                trial_period_days:
                  type: integer
                  description: >-
                    Trial length in days; positive integer. **Subscription
                    sessions only** — sending it on a `"payment"` or `"setup"`
                    session is rejected with a `400`. The trial defers the
                    recurring charge only: a one-time price in the same cart is
                    still charged immediately. Trial-end behaviour is OpenLoop's
                    policy and has no request field — a trial that ends with no
                    payment method on file cancels the subscription rather than
                    invoicing it.
                excluded_payment_method_types:
                  type: array
                  items:
                    type: string
                  description: >-
                    Payment method types the session must not offer; the
                    account's other enabled methods still show. Values are the
                    payment provider's payment method type names (e.g. `card`,
                    `klarna`, `affirm`, `afterpay_clearpay`), matched exactly
                    and forwarded unchanged. `gopay`, `paypay`, `qris`,
                    `rechnung` and `shopeepay` are not yet accepted. Accepted on
                    every session type. Excluding `card` also removes the
                    card-based express buttons (Apple Pay, Link); wallets that
                    are their own type, such as `amazon_pay` and `cashapp`, stay
                    until excluded themselves. Excluding `klarna` alone can
                    still leave Klarna available through Link; `link` is not an
                    accepted value, and Link goes away only when `card` is
                    excluded. An empty array, `null`, a non-array, a non-string
                    entry or a value that is not accepted is rejected with a
                    `400`, and only the last of these names the value.
                provider_payment_method_configuration_id:
                  type: string
                  description: >-
                    Id of a payment method configuration on your payment
                    provider account. The session offers only the methods that
                    configuration enables; without it the account's default
                    configuration applies. Forwarded unchanged, and may be sent
                    together with `excluded_payment_method_types` to narrow the
                    configuration further. `null`, a non-string, or an empty or
                    whitespace-only value is rejected with a `400`; an id the
                    payment provider doesn't recognise returns the provider's
                    error as a `400`. The payment provider's own eligibility
                    rules still apply on top (for example, Affirm and Afterpay
                    are offered only to buyers in the account's own country); if
                    the restrictions leave nothing to offer, the session is
                    still created with a `200`, but its hosted page shows no
                    payment methods.
                metadata:
                  type: object
                  properties:
                    order_id:
                      type: string
                  description: >-
                    Custom metadata merged onto the checkout session and the
                    mode-specific sub-object. Distinct from
                    `customer_data.metadata`, which only affects the customer
                    record. Values must be strings. The `source` key is
                    reserved. Forwarded to the payment provider and republished
                    in events — do not include PHI or PII.
              required:
                - type
            example:
              ui_mode: embedded
              type: payment
              customer_data:
                name: Example Customer
                email: customer@example.com
              items:
                - provider_price_id: test_price_id
                  quantity: 1
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      provider_checkout_session_id:
                        type: string
                        description: Provider checkout session ID.
                      provider_customer_id:
                        type:
                          - string
                          - 'null'
                        description: the payment provider Customer ID or null.
                      type:
                        type: string
                        description: Session type.
                      ui_mode:
                        type: string
                        description: >-
                          Echoes the requested value: `"embedded"`/`"hosted"`
                          (legacy) or `"embedded_page"`/`"hosted_page"`
                          (dahlia).
                      publishable_key:
                        type:
                          - string
                          - 'null'
                        description: >-
                          the payment provider publishable key for embedded
                          mode; null for hosted.
                      client_secret:
                        type:
                          - string
                          - 'null'
                        description: >-
                          the payment provider client secret for embedded mode;
                          null for hosted.
                      url:
                        type:
                          - string
                          - 'null'
                        description: Checkout URL for hosted mode; null for embedded.
                required:
                  - data
              example:
                data:
                  provider_checkout_session_id: test_checkout_session_id
                  provider_customer_id: test_customer_id
                  type: payment
                  ui_mode: embedded
                  publishable_key: test_publishable_key
                  client_secret: test_checkout_session_key
                  url: null
        '400':
          description: >-
            ValidationError: an invalid `ui_mode`; a missing required field,
            including `return_url` when `ui_mode` is `"elements"` and `currency`
            when `type` is `"setup"`; a malformed or non-`http(s)`
            `success_url`, `return_url` or `cancel_url`; a `cancel_url` sent
            when `ui_mode` does not resolve to a hosted page; both
            `provider_coupon_ids` and `provider_promotion_code_ids`; invalid
            `metadata`; an unsupported `type`; failed items validation; a
            subscription session whose `items` hold two or more recurring
            entries, including the same recurring price on two lines (`A
            subscription can have only one recurring price. Create a separate
            subscription for each recurring product.` — checked before the
            session is created, so no session is created and nothing is
            charged); a `trial_period_days` that is not a positive integer or
            was sent on a non-subscription session; an
            `excluded_payment_method_types` that is not a non-empty array of
            accepted values; or a `provider_payment_method_configuration_id`
            that is not a non-empty string. ProviderError: a subscription
            session whose `items` carry no recurring price — the payment
            provider rejects this at session creation and its message is
            surfaced as-is; or a `provider_payment_method_configuration_id` the
            payment provider rejects, such as an id that doesn't exist on the
            account.
        '401':
          description: Missing or invalid bearer token.
        '403':
          description: >-
            No configuration exists for your account, or provider access has
            been disabled for it. A permission failure at the payment provider,
            for example while reading the prices of a subscription cart of two
            or more lines, also returns `403`.
        '404':
          description: >-
            NotFoundError: the configuration resolved for your account was
            deleted between resolution and the provider call (a rare race).
            Also, in a subscription session of two or more lines, a price that
            is unknown to your account (`items price not found: <id>`).
        '500':
          description: Payment provider integration error.
      security:
        - serviceToken: []
        - userToken: []
components:
  schemas:
    CartItem:
      type: object
      properties:
        provider_price_id:
          type: string
          description: Provider price ID.
        quantity:
          type: number
          description: Defaults to 1; must be positive integer.
      required:
        - provider_price_id
  securitySchemes:
    serviceToken:
      type: oauth2
      description: >-
        Service (M2M) access token issued by POST /auth/token using the
        client_credentials grant. Required scopes, where known, are listed on
        each operation below.
      flows:
        clientCredentials:
          tokenUrl: https://api.openloophealth.com/v0.1/auth/token
          scopes: {}
    userToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        User access token issued by POST /auth/token via the verification-code
        grant (after Verify a one-time code) or the refresh_token grant.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.