Create embedded card charge
Create embedded card charge
Overview
Create embedded card charge
Creates a card charge for embedded checkout and returns client_secret for client-side confirmation.
When to use this
Use for in-app card entry where you own the product UI and tokenization flow.
Good to know
Never log or expose client_secret publicly; treat it like a short-lived capability for the client SDK.
See also
Create checkout session if you prefer hosted card collection.
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 /charge/card
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
JSON request payload.
Schema: CreateCardChargeDto
| Field | Required | Type | Description |
|---|---|---|---|
amount | Yes | number | Amount to charge in the original currency |
currency_code | No | enum ("XOF", "USD", "EUR") | Currency code |
currency | No | enum ("XOF", "USD", "EUR") | Backward-compatible alias for currency_code. Use currency_code in new integrations. |
customer_id | No | string | Internal customer UUID (v4). Alternative: send customer_email + customer_name to create/find a customer. |
customer_email | No | string | Customer email, required together with customer_name when customer_id is omitted. |
customer_name | No | string | Customer display name, required together with customer_email when customer_id is omitted. |
customer_phone | No | string | Customer phone number |
description | No | string | Description shown in payment providers and logs |
payment_reference | No | string | Reference included in metadata for reconciliation |
product_id | No | string | Optional product UUID for metadata and reconciliation |
subscription_id | No | string | Optional subscription UUID for metadata and reconciliation |
quantity | No | number | Optional quantity for internal reconciliation |
metadata | No | object | Custom metadata merged into provider metadata |
appearance_theme | No | enum ("light", "dark", "flat") | Optional Payment Element theme for client-side card UI: light, dark, or flat. |
appearance_border_radius | No | number | Optional Payment Element border radius (px) returned for client-side rendering. |
appearance_billing_address | No | enum ("auto", "never") | Optional Payment Element billing address collection mode. Use never to hide country/address selector in Payment Element UI. |
Example body:
{
"amount": 10000
}Responses
| Status | Description |
|---|---|
201 | Card charge created |
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
curl -sS -X POST "https://sandbox.api.lomi.africa/charge/card" \
-H "X-API-KEY: $LOMI_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":10000}'OpenAPI
- operationId:
ChargesController_createCardCharge - Operation:
POST /charge/card
Full schemas and Try it: API reference. Machine-readable contract: repo apps/docs/openapi.json.