> ## 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. # Create Checkout Session > Creates a new checkout session to initiate a user payment experience. ## OpenAPI ````yaml post /v1/checkout-sessions openapi: 3.0.3 info: title: Monime API description: Monime REST API. Please visit https://docs.momime.io/api for more details. termsOfService: https://monime.io/legal/terms-of-service contact: name: Monime Developers url: https://github.com/monimesl email: dev@monime.io version: v1 servers: - url: https://api.monime.io/ security: - bearerAuth: [] paths: /v1/checkout-sessions: post: tags: - Checkout Session summary: Create Checkout Session description: Creates a new checkout session to initiate a user payment experience. operationId: CreateCheckoutSession parameters: - name: Idempotency-Key in: header description: >- This header is used to uniquely identify a logical request, ensuring that it is not processed more than once during retries. required: true schema: maxLength: 64 type: string description: >- This header is used to uniquely identify a logical request, ensuring that it is not processed more than once during retries. - name: Monime-Version in: header description: Specifies which version of the Monime API will handle this request. schema: enum: - caph.2025-08-23 - caph.2025-06-20 type: string description: >- Specifies which version of the Monime API will handle this request. nullable: true - name: Monime-Space-Id in: header description: >- The value is the tenancy parameter that Monime uses to determine which space the request is intended for. required: true schema: maxLength: 64 pattern: ^spc-.*$ type: string description: >- The value is the tenancy parameter that Monime uses to determine which space the request is intended for. requestBody: content: application/json: schema: title: CreateCheckoutSession required: - name - lineItems type: object properties: name: maxLength: 150 type: string description: >- Title or label for the checkout session. Used for display in customer-facing UIs. description: maxLength: 1000 type: string description: >- Optional long-form description explaining the purpose or context of the checkout session. nullable: true cancelUrl: maxLength: 255 type: string description: >- 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. format: url successUrl: maxLength: 255 type: string description: >- 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. format: url callbackState: maxLength: 255 type: string description: >- Opaque value sent back via callback for correlating the session. Never exposed in read APIs. nullable: true reference: maxLength: 255 type: string description: >- Optional external reference identifier (e.g., order ID) used to link this session with the developer’s backend system. nullable: true financialAccountId: maxLength: 100 type: string description: >- Financial account where collected funds are settled. Defaults to the main account if omitted. nullable: true lineItems: maxItems: 16 minItems: 1 type: array items: type: object oneOf: - title: Custom Item (User Defined) required: - name - price type: object properties: type: enum: - custom type: string description: Type of line item. This must be set to 'custom'. id: type: string description: >- 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. readOnly: true name: maxLength: 100 type: string description: >- Name of the product or service represented by this line item. price: type: object properties: currency: type: string description: >- The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE' value: type: integer description: >- 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. additionalProperties: false description: >- Monetary value representing the price per unit of this item. quantity: maximum: 100000 minimum: 1 type: integer description: >- Number of units being purchased. Must be between 1 and 100,000. default: 1 reference: maxLength: 100 type: string description: >- 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. nullable: true description: maxLength: 100 type: string description: >- Optional description providing additional details about the item. nullable: true images: maxItems: 3 uniqueItems: true type: array items: type: string description: A URL description: >- Up to 3 image URLs visually representing this item. nullable: true additionalProperties: false description: >- A user-defined line item with specified name, quantity, and price. properties: type: enum: - custom type: string default: custom description: >- List of items to be displayed and charged in the session. Must include at least one item. nullable: true paymentOptions: title: PaymentOptions type: object properties: card: type: object properties: disable: type: boolean description: >- When true, card-based payment options will be hidden or disabled during checkout. default: false additionalProperties: false description: >- Settings for card-based payments. Allows disabling the card method entirely. bank: type: object properties: disable: type: boolean description: >- When true, bank-based payment options will be hidden or disabled during checkout. default: false enabledProviders: uniqueItems: true type: array items: enum: - slb001 - slb004 - slb007 type: string description: >- The ID of the bank as identified by Monime. E.g. slb001 to denote SLCB description: >- Bank providers to explicitly allow for this session. Takes precedence over 'disabledProviders'. nullable: true disabledProviders: uniqueItems: true type: array items: enum: - slb001 - slb004 - slb007 type: string description: >- The ID of the bank as identified by Monime. E.g. slb001 to denote SLCB description: >- 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. nullable: true additionalProperties: false description: >- Settings for bank payments. You can restrict which bank providers are available or excluded. momo: type: object properties: disable: type: boolean description: >- When true, mobile money (MoMo) options will be hidden or disabled during checkout. default: false enabledProviders: uniqueItems: true type: array items: enum: - m17 - m18 type: string description: >- The ID of the MOMO as identified by Monime. E.g. m17 to denote Orange Money SL description: >- MoMo providers to explicitly allow for this session. Takes precedence over 'disabledProviders'. nullable: true disabledProviders: uniqueItems: true type: array items: enum: - m17 - m18 type: string description: >- The ID of the MOMO as identified by Monime. E.g. m17 to denote Orange Money SL description: >- MoMo providers to exclude from this session. If a provider is in both enabled and disabled lists, it will be allowed. nullable: true additionalProperties: false description: >- Settings for mobile money payments. Customize which MoMo providers are shown at checkout. wallet: type: object properties: disable: type: boolean description: >- When true, wallet-based payment options will be hidden or disabled during checkout. default: false enabledProviders: uniqueItems: true type: array items: enum: - dw001 type: string description: >- The ID of the digital wallet as identified by Monime. E.g. dw001 to denote SafulPay description: >- Wallet providers to explicitly allow for this session. Takes precedence over 'disabledProviders'. nullable: true disabledProviders: uniqueItems: true type: array items: enum: - dw001 type: string description: >- The ID of the digital wallet as identified by Monime. E.g. dw001 to denote SafulPay description: >- Wallet providers to exclude from this session. If a provider is in both enabled and disabled lists, it will be allowed. nullable: true additionalProperties: false description: >- Settings for wallet-based payments. Control whether wallets are available and which ones. additionalProperties: false description: >- **Payment method configuration** that controls which payment options (e.g., Banks, Cards, MOMO, Wallets) are enabled or restricted during checkout. nullable: true brandingOptions: type: object properties: primaryColor: maxLength: 255 type: string description: >- Primary brand color in hex format (e.g., '#00FF00') used to customize the appearance of the checkout interface. additionalProperties: false description: >- Visual customization options for the checkout UI, such as color schemes or logos. nullable: true metadata: maxProperties: 64 type: object additionalProperties: maxLength: 100 type: string description: >- Metadata values are free-form strings up to 100 characters. description: Key-value pairs for attaching contextual metadata. nullable: true additionalProperties: false description: >- Creates a new checkout session to initiate a user payment experience. responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean description: >- Represents the status of the query operation, confirming if it was successful. This field is always true messages: type: array items: {} description: >- Contains a list of messages providing relevant information or feedback related to the query or operation result: $ref: '#/components/schemas/CheckoutSession' components: schemas: CheckoutSession: title: Checkout Session type: object properties: id: type: string description: Unique identifier of the checkout session. status: enum: - pending - cancelled - expired - completed type: string description: |- **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: type: string description: >- Title or label for the checkout session. Used for display in customer-facing UIs. orderNumber: type: string description: >- Internally generated order number that uniquely identifies the payment associated to this checkout session. nullable: true reference: type: string description: >- Optional external reference identifier (e.g., order ID) used to link this session with the developer’s backend system. nullable: true description: type: string description: >- Optional long-form description explaining the purpose or context of the checkout session. nullable: true redirectUrl: type: string description: >- The URL where the customer should be redirected to begin the checkout session. This is typically a hosted checkout page managed by Monime. cancelUrl: type: string description: >- 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. format: url successUrl: type: string description: >- 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. format: url lineItems: type: object properties: data: type: array items: type: object oneOf: - title: Custom Item (User Defined) required: - name - price type: object properties: type: enum: - custom type: string description: Type of line item. This must be set to 'custom'. id: type: string description: >- 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. readOnly: true name: maxLength: 100 type: string description: >- Name of the product or service represented by this line item. price: type: object properties: currency: type: string description: >- The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE' value: type: integer description: >- 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. additionalProperties: false description: >- Monetary value representing the price per unit of this item. quantity: maximum: 100000 minimum: 1 type: integer description: >- Number of units being purchased. Must be between 1 and 100,000. default: 1 reference: maxLength: 100 type: string description: >- 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. nullable: true description: maxLength: 100 type: string description: >- Optional description providing additional details about the item. nullable: true images: maxItems: 3 uniqueItems: true type: array items: type: string description: A URL description: Up to 3 image URLs visually representing this item. nullable: true additionalProperties: false description: >- A user-defined line item with specified name, quantity, and price. properties: type: enum: - custom type: string default: custom description: >- Array of individual line items representing products or services included in the checkout session. Each item specifies details like name, quantity, and unit price. nullable: true description: >- 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. financialAccountId: type: string description: >- Financial account where the collected funds were settled. Defaults to the main account if omitted. nullable: true brandingOptions: type: object properties: primaryColor: maxLength: 255 type: string description: >- Primary brand color in hex format (e.g., '#00FF00') used to customize the appearance of the checkout interface. additionalProperties: false description: >- Visual customization options for the checkout UI, such as color schemes or logos. nullable: true expireTime: type: string description: >- The timestamp at which the checkout session will automatically expire. format: date-time createTime: type: string description: Timestamp indicating when the checkout session was created. format: date-time ownershipGraph: title: OwnershipGraph type: object properties: owner: title: OwnershipObject type: object properties: id: type: string description: '**Unique ID** of the object instance that owns this entity.' readOnly: true type: type: string description: >- **Type of the object** that owns this entity. Examples include: 'internal_transfer', 'checkout_session', 'payment_code'. readOnly: true metadata: maxProperties: 64 type: object additionalProperties: maxLength: 100 type: string description: >- Metadata values are free-form strings up to 100 characters. description: '**Arbitrary metadata** describing the owning object.' nullable: true readOnly: true owner: $ref: '#/components/schemas/CoreresourcesParentOwningObject' additionalProperties: false description: >- **Immediate object** that owns this entity. This is the direct originator or source object. readOnly: true additionalProperties: false description: >- **Ownership graph** that traces the origin of this checkout session, enabling deep auditability and understanding of its creation context. nullable: true metadata: maxProperties: 64 type: object additionalProperties: maxLength: 100 type: string description: Metadata values are free-form strings up to 100 characters. description: >- Structured key-value metadata for tagging the session with contextual or custom information. nullable: true description: > 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. CoreresourcesParentOwningObject: title: OwnershipObject type: object properties: id: type: string description: '**Unique ID** of the object instance that owns this entity.' readOnly: true type: type: string description: >- **Type of the object** that owns this entity. Examples include: 'internal_transfer', 'checkout_session', 'payment_code'. readOnly: true metadata: maxProperties: 64 type: object additionalProperties: maxLength: 100 type: string description: Metadata values are free-form strings up to 100 characters. description: '**Arbitrary metadata** describing the owning object.' nullable: true readOnly: true owner: $ref: '#/components/schemas/CoreresourcesParentOwningObject' additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: auth-scheme description: >- Bearer HTTP authentication specified with the header Authorization: Bearer ````