Checkout Sessions

The Checkout Sessions API allows you to create secure, temporary sessions that represent a customer’s intent to pay. You redirect your customer to the lomi.-hosted checkout page associated with the session to complete the payment.

Authentication

Requests require authentication using your API key in the `X-API-Key` header. The associated Merchant ID is typically inferred from the key. See the Authentication guide.

The checkout session object

Represents a single checkout attempt, containing details about the payment, customer information (if provided), associated resources (like products or plans), and the session’s status and URL. See Data Models for the full structure (Note: This link assumes the object will be added to data-models.mdx).

Session lifecycle

1. Create: You create a session via the API, specifying the amount, currency, allowed providers, and redirect URLs.
2. Redirect: You receive a unique `url` in the response and redirect your customer to this generated checkout page.
3. Payment: The customer selects a payment method and completes the payment on the page.
4. Status Update: The session `status` changes to `completed` or `expired`.
5. Redirect Back: lomi. redirects the customer back to your `success_url` or `cancel_url`.
6. Verification: You should verify the outcome by listening for webhook events (e.g., `checkout.session.completed`) or by retrieving the session status via the API.

Endpoints

Create checkout session

Creates a new checkout session.

Endpoint: `POST /checkout-sessions`

Request body parameters:

Example request:

{
  "success_url": "https://your-site.com/order/success?",
  "cancel_url": "https://your-site.com/cart",
  "allowed_providers": ["WAVE", "ORANGE"],
  "amount": 10000,
  "currency_code": "XOF",
  "title": "Your Order Summary",
  "metadata": { "internal_order_ref": "ORD-12345" }
}

Example response (201 Created):

{
  "data": {
    "checkout_session_id": "a465993b-98fb-49c3-9943-5b8eac17004c",
    "url": "https://checkout.lomi.africa/checkout/a465993b-98fb-49c3-9943-5b8eac17004c", // Redirect customer here
    "status": "open", // Initial status
    "expires_at": "2025-04-04T15:21:49.955Z", // Based on expiration_minutes
    "created_at": "2025-04-04T14:21:49.955Z",
    "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
    "organization_id": "0979ec77-9fb1-4c9a-8c55-d7fb6c182c9c",
    "success_url": "https://your-site.com/order/success?",
    "cancel_url": "https://your-site.com/cart",
    "amount": 10000,
    "currency_code": "XOF",
    "allowed_providers": ["WAVE", "ORANGE"],
    "title": "Your Order Summary",
    "public_description": null,
    "customer_email": null,
    "customer_name": null,
    "customer_phone": null,
    "product_id": null,
    "subscription_id": null,
    "plan_id": null,
    "allow_coupon_code": false,
    "metadata": { "internal_order_ref": "ORD-12345" },
    "environment": "live" // Or "test"
  }
}

Get checkout session

Retrieves the details and current status of a specific checkout session.

Endpoint: `GET /checkout-sessions/{id}`

Path parameters:

Example response (200 OK):

{
  "data": {
    "checkout_session_id": "a465993b-98fb-49c3-9943-5b8eac17004c",
    "status": "completed", // Could be open, completed, expired
    // ... all other fields as shown in the create response
    "updated_at": "2025-04-04T14:55:00.123Z" // Updated when status changes
  }
}

List checkout sessions

Retrieves a list of checkout sessions associated with your merchant account, with options for filtering and pagination.

Endpoint: `GET /checkout-sessions`

Query parameters:

Example response (200 OK):

{
  "data": [
    {
      "checkout_session_id": "a465993b-98fb-49c3-9943-5b8eac17004c",
      "status": "completed",
      // ... other fields
    },
    {
      "checkout_session_id": "b5760a4c-a9cc-50d4-a054-6c9fbd28115d",
      "status": "expired",
      // ... other fields
    }
    // ... more sessions
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20
    // Potentially other pagination fields like total_count, total_pages
  }
}

Webhooks

Listen for webhook events to be notified when a session is completed or expires, rather than relying solely on polling the API.

• `checkout.session.completed`: Sent when a payment is successfully completed through the session.
• `checkout.session.expired`: Sent when an open session passes its expiration time without being completed.

See the Webhooks guide for configuration details.

Error handling

Common errors include `400 Bad Request` for invalid input (missing required fields, invalid URLs, invalid provider codes), `401 Unauthorized`, `403 Forbidden` if the session doesn’t belong to the merchant, `404 Not Found` if the session ID doesn’t exist, and `500 Internal Server Error`. Refer to the Errors guide for general structure and handling.