# Create checkout session
Source: https://docs.lomi.africa/api/checkout-sessions/CheckoutSessionsController_create

Create checkout session

***

title: "Create checkout session"
description: "Create checkout session"
full: true
method: post
path: /checkout-sessions
operationId: CheckoutSessionsController\_create
-----------------------------------------------

## Overview

Create checkout session

Creates a hosted checkout session so the buyer completes payment on the hosted checkout experience. Sessions expire; create a fresh session if the link lapses.

### When to use this

Use for e-commerce, invoices, or any flow where you want lomi. to host payment collection and return the customer to your site.

### Good to know

Prefer checkout sessions over ad-hoc charges when you need a consistent buyer experience across payment methods. For pay\_what\_you\_want products, amount must fall within the linked price minimum\_amount and maximum\_amount bounds (unit × quantity).

### See also

[Payment links](/api/payment-links/PaymentLinksController_create) · [Retrieve checkout session](/api/checkout-sessions/CheckoutSessionsController_findOne)

## Authentication

Merchant routes require an API key in the `X-API-KEY` header (see [Integration overview](/api)). Use a **test** key against `https://sandbox.api.lomi.africa` and a **live** key against `https://api.lomi.africa`.

## Endpoint

`POST /checkout-sessions`

Base URLs:

* `https://sandbox.api.lomi.africa`
* `https://api.lomi.africa`

## Request

### Path parameters

*No path parameters beyond the URL pattern.*

### Query parameters

*No query parameters.*

### Headers

| Name           | In     | Required | Schema | Description                                                                                                                                          |
| -------------- | ------ | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Lomi-Account` | header | No       | -      | Optional lomi. Network account id (`acct_...`). When present, the API key acts as the Operator and the request targets the connected Member Account. |

### Request body

Session payload: provide `amount` (and optional product fields) or `line_items` for a multi-product cart.

Schema: `object`

| Field                     | Required | Type                                                                          | Description                                                                            |
| ------------------------- | -------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `amount`                  | Yes      | `number`                                                                      | -                                                                                      |
| `currency_code`           | No       | `enum ("XOF", "USD", "EUR", "XAF", "GHS", "KES", "MAD", "ZAR", "GBP", "CAD")` | Optional. Falls back to organization default\_currency when omitted.                   |
| `title`                   | No       | `string`                                                                      | -                                                                                      |
| `description`             | No       | `string`                                                                      | -                                                                                      |
| `customer_id`             | No       | `string`                                                                      | -                                                                                      |
| `customer_email`          | No       | `string`                                                                      | -                                                                                      |
| `customer_name`           | No       | `string`                                                                      | -                                                                                      |
| `customer_phone`          | No       | `string`                                                                      | -                                                                                      |
| `customer_city`           | No       | `string`                                                                      | -                                                                                      |
| `customer_country`        | No       | `string`                                                                      | -                                                                                      |
| `customer_address`        | No       | `string`                                                                      | -                                                                                      |
| `customer_postal_code`    | No       | `string`                                                                      | -                                                                                      |
| `product_id`              | No       | `string`                                                                      | -                                                                                      |
| `price_id`                | No       | `string`                                                                      | -                                                                                      |
| `subscription_id`         | No       | `string`                                                                      | -                                                                                      |
| `allow_quantity`          | No       | `boolean`                                                                     | -                                                                                      |
| `quantity`                | No       | `number`                                                                      | -                                                                                      |
| `success_url`             | No       | `string`                                                                      | -                                                                                      |
| `cancel_url`              | No       | `string`                                                                      | -                                                                                      |
| `allow_coupon_code`       | No       | `boolean`                                                                     | -                                                                                      |
| `require_billing_address` | No       | `boolean`                                                                     | When true, show and require billing address on checkout. Default false when unset.     |
| `require_email`           | No       | `boolean`                                                                     | When true, show and require customer email. Default true when unset.                   |
| `require_phone`           | No       | `boolean`                                                                     | When true, show and require customer phone. Default true when unset.                   |
| `require_name`            | No       | `boolean`                                                                     | When true, show and require customer name. Default true when unset.                    |
| `fields`                  | No       | `array<object>`                                                               | Optional ordered checkout field schema. When provided, overrides require\_\* booleans. |
| `payment_link_id`         | No       | `string`                                                                      | -                                                                                      |
| `metadata`                | No       | `object`                                                                      | -                                                                                      |
| `line_items`              | No       | `array<object>`                                                               | -                                                                                      |

Example body:

```json
{
  "amount": 10000
}
```

## Responses

| Status | Description                                |
| ------ | ------------------------------------------ |
| `201`  | Created successfully                       |
| `400`  | Bad request, invalid or missing parameters |
| `401`  | Invalid or missing API key                 |

## Errors

Errors follow the standard JSON error format (status code and machine-readable message). Validate inputs before calling; **401** indicates a missing/invalid key, **404** a missing resource for this organization, **429** rate limiting. For safe retries on create-style calls, send an idempotency key when your flow supports it.

## Example

```bash
curl -sS -X POST "https://sandbox.api.lomi.africa/checkout-sessions" \
  -H "X-API-KEY: $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":10000}'
```

## OpenAPI

* **operationId**: `CheckoutSessionsController_create`
* **Operation**: `POST /checkout-sessions`

Full schemas and **Try it**: [API reference](/api). Machine-readable contract: repo `apps/docs/openapi.json`.
