---
title: "Create Checkout Session"
method: POST
path: "/v1/checkout-sessions"
tags: ["Checkout Session"]
---

# Create Checkout Session

`POST /v1/checkout-sessions`

Creates a new checkout session to initiate a user payment experience.

## Headers

- `Idempotency-Key` string, required — This header is used to uniquely identify a logical request, ensuring that it is not processed more than once during retries.
- `Monime-Version` 'caph.2025-08-23' | 'caph.2025-06-20', nullable — Specifies which version of the Monime API will handle this request.
- `Monime-Space-Id` string, required — The value is the tenancy parameter that Monime uses to determine which space the request is intended for.

## Request body

- object — Creates a new checkout session to initiate a user payment experience.
  - `name` string, required — Title or label for the checkout session. Used for display in customer-facing UIs.
  - `description` string, nullable — Optional long-form description explaining the purpose or context of the checkout session.
  - `cancelUrl` string, url — 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.
  - `successUrl` string, url — 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.
  - `callbackState` string, nullable — Opaque value sent back via callback for correlating the session. Never exposed in read APIs.
  - `reference` string, nullable — Optional external reference identifier (e.g., order ID) used to link this session with the developer’s backend system.
  - `financialAccountId` string, nullable — Financial account where collected funds are settled. Defaults to the main account if omitted.
  - `lineItems` object[], nullable, required — List of items to be displayed and charged in the session. Must include at least one item.
    - `type` 'custom' — Type of line item. This must be set to 'custom'.
    - `id` string — Unique internal identifier for this line item. This is generated by the system and cannot be provided by the user. Unique across all checkout sessions.
    - `name` string, required — Name of the product or service represented by this line item.
    - `price` object, required — Monetary value representing the price per unit of this item.
      - `currency` string — The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE'
      - `value` integer — The value representation in the currency's minor unit. E.g. For 1 Leone (SLE 1), the value should be 100, denoting cents, the minor unit.
    - `quantity` integer — Number of units being purchased. Must be between 1 and 100,000.
    - `reference` string, nullable — External system-provided identifier for this line item, used for cross-system tracking, reconciliation, or referencing purposes. Must be unique within the checkout session. If not provided, a unique identifier will be generated.
    - `description` string, nullable — Optional description providing additional details about the item.
    - `images` string[], nullable — Up to 3 image URLs visually representing this item.
  - `paymentOptions` object, nullable — **Payment method configuration** that controls which payment options (e.g., Banks, Cards, MOMO, Wallets) are enabled or restricted during checkout.
    - `card` object — Settings for card-based payments. Allows disabling the card method entirely.
      - `disable` boolean — When true, card-based payment options will be hidden or disabled during checkout.
    - `bank` object — Settings for bank payments. You can restrict which bank providers are available or excluded.
      - `disable` boolean — When true, bank-based payment options will be hidden or disabled during checkout.
      - `enabledProviders` string[], nullable — Bank providers to explicitly allow for this session. Takes precedence over 'disabledProviders'.
      - `disabledProviders` string[], nullable — If set, these bank providers will be excluded from this session. If a provider is in both enabled and disabled lists, it will be allowed.
    - `momo` object — Settings for mobile money payments. Customize which MoMo providers are shown at checkout.
      - `disable` boolean — When true, mobile money (MoMo) options will be hidden or disabled during checkout.
      - `enabledProviders` string[], nullable — MoMo providers to explicitly allow for this session. Takes precedence over 'disabledProviders'.
      - `disabledProviders` string[], nullable — MoMo providers to exclude from this session. If a provider is in both enabled and disabled lists, it will be allowed.
    - `wallet` object — Settings for wallet-based payments. Control whether wallets are available and which ones.
      - `disable` boolean — When true, wallet-based payment options will be hidden or disabled during checkout.
      - `enabledProviders` string[], nullable — Wallet providers to explicitly allow for this session. Takes precedence over 'disabledProviders'.
      - `disabledProviders` string[], nullable — Wallet providers to exclude from this session. If a provider is in both enabled and disabled lists, it will be allowed.
  - `brandingOptions` object, nullable — Visual customization options for the checkout UI, such as color schemes or logos.
    - `primaryColor` string — Primary brand color in hex format (e.g., '#00FF00') used to customize the appearance of the checkout interface.
  - `metadata` object, nullable — Key-value pairs for attaching contextual metadata.

## Response `200`

OK

- object
  - `success` boolean — Represents the status of the query operation, confirming if it was successful. This field is always true
  - `messages` unknown[] — Contains a list of messages providing relevant information or feedback related to the query or operation
    - unknown
  - `result` CheckoutSession — 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.
    - `id` string — Unique identifier of the checkout session.
    - `status` 'pending' | 'cancelled' | 'expired' | 'completed' — **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.
    - `name` string — Title or label for the checkout session. Used for display in customer-facing UIs.
    - `orderNumber` string, nullable — Internally generated order number that uniquely identifies the payment associated to this checkout session.
    - `reference` string, nullable — Optional external reference identifier (e.g., order ID) used to link this session with the developer’s backend system.
    - `description` string, nullable — Optional long-form description explaining the purpose or context of the checkout session.
    - `redirectUrl` string — The URL where the customer should be redirected to begin the checkout session. This is typically a hosted checkout page managed by Monime.
    - `cancelUrl` string, url — 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.
    - `successUrl` string, url — 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.
    - `lineItems` 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.
      - `data` object[], nullable — Array of individual line items representing products or services included in the checkout session. Each item specifies details like name, quantity, and unit price.
        - `type` 'custom' — Type of line item. This must be set to 'custom'.
        - `id` string — Unique internal identifier for this line item. This is generated by the system and cannot be provided by the user. Unique across all checkout sessions.
        - `name` string, required — Name of the product or service represented by this line item.
        - `price` object, required — Monetary value representing the price per unit of this item.
          - `currency` string — The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE'
          - `value` integer — The value representation in the currency's minor unit. E.g. For 1 Leone (SLE 1), the value should be 100, denoting cents, the minor unit.
        - `quantity` integer — Number of units being purchased. Must be between 1 and 100,000.
        - `reference` string, nullable — External system-provided identifier for this line item, used for cross-system tracking, reconciliation, or referencing purposes. Must be unique within the checkout session. If not provided, a unique identifier will be generated.
        - `description` string, nullable — Optional description providing additional details about the item.
        - `images` string[], nullable — Up to 3 image URLs visually representing this item.
    - `financialAccountId` string, nullable — Financial account where the collected funds were settled. Defaults to the main account if omitted.
    - `brandingOptions` object, nullable — Visual customization options for the checkout UI, such as color schemes or logos.
      - `primaryColor` string — Primary brand color in hex format (e.g., '#00FF00') used to customize the appearance of the checkout interface.
    - `expireTime` string, date-time — The timestamp at which the checkout session will automatically expire.
    - `createTime` string, date-time — Timestamp indicating when the checkout session was created.
    - `ownershipGraph` object, nullable — **Ownership graph** that traces the origin of this checkout session, enabling deep auditability and understanding of its creation context.
      - `owner` object — **Immediate object** that owns this entity. This is the direct originator or source object.
        - `id` string — **Unique ID** of the object instance that owns this entity.
        - `type` string — **Type of the object** that owns this entity. Examples include: 'internal_transfer', 'checkout_session', 'payment_code'.
        - `metadata` object, nullable — **Arbitrary metadata** describing the owning object.
        - `owner` CoreresourcesParentOwningObject
          - `id` string — **Unique ID** of the object instance that owns this entity.
          - `type` string — **Type of the object** that owns this entity. Examples include: 'internal_transfer', 'checkout_session', 'payment_code'.
          - `metadata` object, nullable — **Arbitrary metadata** describing the owning object.
          - `owner` CoreresourcesParentOwningObject — recursive
    - `metadata` object, nullable — Structured key-value metadata for tagging the session with contextual or custom information.

---

[API](https://skmtc.dev/monime/apis/monime-api.md) · [All operations](https://skmtc.dev/monime/apis/monime-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/monime/monime-api/revisions/bd7f875ea428/schema)