Create checkout session
Create checkout session
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). currency_code is optional and falls back to your organization default configured under Settings → Checkout → Payments.
See also
Payment links · Retrieve checkout session
Authentication
Merchant routes require an API key in the X-API-KEY header (see Integration overview). 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.africahttps://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 | No | number | - |
currency_code | No | enum ("XOF", "USD", "EUR") | Optional. When omitted, uses the organization default_currency from Settings → Checkout → Payments. Must be in the organization's allowed_currencies list. |
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 fields. Default when unset follows org checkout settings, then false. See Checkout form fields. |
require_name | No | boolean | When true, show and require customer name. When false, hide the name field (display name falls back to email or phone). Default when unset: true. See Checkout form fields. |
require_email | No | boolean | When true, show and require email. When false, hide email. Default when unset: true. See Checkout form fields. |
require_phone | No | boolean | When true, show and require phone. When false, phone is optional if email is visible, or hidden if email is hidden. Default when unset: false. See Checkout form fields. |
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:
{
"currency_code": "XOF"
}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
Minimal session:
curl -sS -X POST "https://sandbox.api.lomi.africa/checkout-sessions" \
-H "X-API-KEY: $LOMI_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"currency_code":"XOF"}'Phone-only checkout (name, email, and billing address hidden):
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": 1000,
"currency_code": "XOF",
"require_name": false,
"require_email": false,
"require_phone": true,
"require_billing_address": false
}'See Checkout form fields for all flag combinations.
OpenAPI
- operationId:
CheckoutSessionsController_create - Operation:
POST /checkout-sessions
Full schemas and Try it: API reference. Machine-readable contract: repo apps/docs/openapi.json.