Create direct mobile-money charge
Create direct mobile-money charge
Overview
Create direct mobile-money charge
Starts a payer-facing mobile-money charge on a supported rail; the response includes the next step for the customer. Check next_action (redirect with url) in addition to wave_launch_url / checkout_url.
When to use this
Use for server-initiated mobile-money collection when you are not using a hosted checkout session.
Good to know
Follow the provider instructions in the response; UX is rail-specific (USSD, app redirect, etc.).
See also
Mobile money · Direct charges · Create checkout session · Transactions
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/wave
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: CreateWaveChargeDto
| Field | Required | Type | Description |
|---|---|---|---|
amount | Yes | number | Amount in XOF (minimum 100) |
currency | Yes | string | Must be XOF for Wave |
organizationId | No | string | - |
merchantId | No | string | - |
customer | Yes | CustomerDto | - |
description | No | string | - |
successUrl | No | string | - |
errorUrl | No | string | - |
environment | No | enum ("live", "test") | - |
Example body:
{
"amount": 1000,
"currency": "XOF",
"customer": {
"name": "...",
"phoneNumber": "..."
}
}Responses
| Status | Description |
|---|---|
201 | Wave charge initiated |
400 | Invalid input or Wave API error |
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/wave" \
-H "X-API-KEY: $LOMI_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":1000,"currency":"XOF","customer":{"name":"...","phoneNumber":"..."}}'OpenAPI
- operationId:
ChargesController_createWaveCharge - Operation:
POST /charge/wave
Full schemas and Try it: API reference. Machine-readable contract: repo apps/docs/openapi.json.