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

# Checkout Session

A **Checkout Session** represents a Monime-hosted payment flow where customers complete purchases for a defined set of items.\
It is designed for **e-commerce** and **embedded payment scenarios** where merchants want a simple, secure way to accept payments across multiple channels without building the payment UI themselves.

Unlike direct API-based payments, a Checkout Session aggregates **multiple payment methods** — such as **Mobile Money**, **Card**, and **Bank Transfers** — and presents them in a unified checkout experience.

***

### Use Cases

* **E-Commerce Cart Checkout**\
  A customer selects items in a cart. The merchant creates a Hosted Checkout Session, and Monime presents Mobile Money, Card, and Bank options in one unified flow.

* **Embedded SaaS Billing**\
  A SaaS platform embeds a Hosted Checkout Session to bill users. Customers pick their preferred channel (Card, MoMo, Bank), and once payment is confirmed, the SaaS receives `checkout_session.completed`.

* **QR or Link-Based Payment**\
  Merchants generate a checkout session link or QR code. Customers open the hosted page and choose any available payment method.

* **Fallback Across Methods**\
  If a user’s card payment fails, they can seamlessly retry with Mobile Money — all within the same checkout session.

<ResponseExample>
  ```json JSON Model theme={null}
  {
      "id": null,
      "status": "pending",
      "name": null,
      "orderNumber": null,
      "reference": null,
      "description": null,
      "redirectUrl": null,
      "cancelUrl": null,
      "successUrl": null,
      "lineItems": {
          "data": []
      },
      "financialAccountId": null,
      "brandingOptions": {
          "primaryColor": null
      },
      "expireTime": null,
      "createTime": null,
      "ownershipGraph": {
          "owner": {
              "id": null,
              "type": null,
              "metadata": null,
              "": null
          }
      },
      "metadata": null
  }
  ```
</ResponseExample>

<ResponseField name="📋" type="Properties">
  <ResponseField name="id" type="string">
    Unique identifier of the checkout session.
  </ResponseField>

  <ResponseField name="status" type="enum<string>">
    **Status** of the checkout session. Possible values:

    * pending: Awaiting initiation.
    * completed: Checkout completed successfully.
    * cancelled: User cancelled the session.
    * expired: Session expired due to inactivity.

    Available options: <code>pending</code> <code>cancelled</code> <code>expired</code> <code>completed</code>
  </ResponseField>

  <ResponseField name="name" type="string">
    Title or label for the checkout session. Used for display in customer-facing UIs.
  </ResponseField>

  <ResponseField name="orderNumber" type="string">
    Internally generated order number that uniquely identifies the payment associated to this checkout session.
  </ResponseField>

  <ResponseField name="reference" type="string">
    Optional external reference identifier (e.g., order ID) used to link this session with the developer’s backend system.
  </ResponseField>

  <ResponseField name="description" type="string">
    Optional long-form description explaining the purpose or context of the checkout session.
  </ResponseField>

  <ResponseField name="redirectUrl" type="string">
    The URL where the customer should be redirected to begin the checkout session. This is typically a hosted checkout page managed by Monime.
  </ResponseField>

  <ResponseField name="cancelUrl" type="string">
    The URL to redirect the customer to if they cancel the checkout process before completing payment. This typically returns the user to your site or app with context about the cancellation.
  </ResponseField>

  <ResponseField name="successUrl" type="string">
    The URL to redirect the customer to after successfully completing the checkout. Typically used to confirm the order or show a success message on your site or app.
  </ResponseField>

  <ResponseField name="lineItems" type="object">
    Container for the list of items included in the checkout session. Each item represents a product or service being purchased, along with its quantity and pricing.

    <Expandable title="properties">
      <ResponseField name="data" type="array">
        Array of individual line items representing products or services included in the checkout session. Each item specifies details like name, quantity, and unit price.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="financialAccountId" type="string">
    Financial account where the collected funds were settled. Defaults to the main account if omitted.
  </ResponseField>

  <ResponseField name="brandingOptions" type="object">
    Visual customization options for the checkout UI, such as color schemes or logos.

    <Expandable title="properties">
      <ResponseField name="primaryColor" type="string">
        Primary brand color in hex format (e.g., '#00FF00') used to customize the appearance of the checkout interface.

        MaxLength: <code>255</code>
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="expireTime" type="string">
    The timestamp at which the checkout session will automatically expire.
  </ResponseField>

  <ResponseField name="createTime" type="string">
    Timestamp indicating when the checkout session was created.
  </ResponseField>

  <ResponseField name="ownershipGraph" type="object">
    **Ownership graph** that traces the origin of this checkout session, enabling deep auditability and understanding of its creation context.

    <Expandable title="properties">
      <ResponseField name="owner" type="object">
        **Immediate object** that owns this entity. This is the direct originator or source object.

        <Expandable title="properties">
          <ResponseField name="id" type="string">
            **Unique ID** of the object instance that owns this entity.
          </ResponseField>

          <ResponseField name="type" type="string">
            **Type of the object** that owns this entity. Examples include: 'internal\_transfer', 'checkout\_session', 'payment\_code'.
          </ResponseField>

          <ResponseField name="metadata" type="object">
            **Arbitrary metadata** describing the owning object.
          </ResponseField>

          <ResponseField name="" type="" />
        </Expandable>
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="metadata" type="object">
    Structured key-value metadata for tagging the session with contextual or custom information.
  </ResponseField>
</ResponseField>