NewDash Dots are hereMini apps in Dash, with payments built inLearn more
Docs

Checkout Session

Create Checkout Session

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

POST
/v1/checkout-sessions

Authorization

Authorizationstringheaderrequired

Bearer HTTP authentication specified with the header Authorization: Bearer <access_token>

Headers

Idempotency-Keystringrequired

This header is used to uniquely identify a logical request, ensuring that it is not processed more than once during retries.

Length:length <= 64
Monime-Versionstring | nulloptional

Specifies which version of the Monime API will handle this request.

Available options:caph.2025-08-23caph.2025-06-20
Monime-Space-Idstringrequired

The value is the tenancy parameter that Monime uses to determine which space the request is intended for.

Match:^spc-.*$
Length:length <= 64

Body

application/json
namestringrequired

Title or label for the checkout session. Used for display in customer-facing UIs.

Length:length <= 150
lineItemsarray | nullrequired

List of items to be displayed and charged in the session. Must include at least one item.

Items:1 <= items <= 16
descriptionstring | nulloptional

Optional long-form description explaining the purpose or context of the checkout session.

Length:length <= 1000
cancelUrlstringoptional

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
Length:length <= 255
successUrlstringoptional

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
Length:length <= 255
callbackStatestring | nulloptional

Opaque value sent back via callback for correlating the session. Never exposed in read APIs.

Length:length <= 255
referencestring | nulloptional

Optional external reference identifier (e.g., order ID) used to link this session with the developer’s backend system.

Length:length <= 255
financialAccountIdstring | nulloptional

Financial account where collected funds are settled. Defaults to the main account if omitted.

Length:length <= 100
paymentOptionsobject | nulloptional

Payment method configuration that controls which payment options (e.g., Banks, Cards, MOMO, Wallets) are enabled or restricted during checkout.

brandingOptionsobject | nulloptional

Visual customization options for the checkout UI, such as color schemes or logos.

metadataobject | nulloptional

Key-value pairs for attaching contextual metadata.

Properties:properties <= 64

Response

200 - application/json

OK

successbooleanoptional

Represents the status of the query operation, confirming if it was successful. This field is always true

messagesarray<unknown>optional

Contains a list of messages providing relevant information or feedback related to the query or operation

resultCheckout Sessionoptional

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.

Status