How do I accept Wave payments?
Wave mobile money via hosted checkout or POST /charge/wave, with async live behavior and XOF requirements.
Wave is the primary mobile-money rail for UEMOA (XOF) merchants. Most teams should use hosted checkout or payment links first.
Hosted checkout (recommended)
- Create a checkout session with
currency_code: "XOF". - Customer selects Wave on the hosted page.
- Customer approves in the Wave app.
- Confirm with webhooks or
GET /transactions/{id}before fulfilling.
Direct charge
POST /charge/wave requires XOF and a nested customer object with name and phoneNumber in E.164 format. The response includes wave_launch_url or checkout_url: redirect or deep-link the customer.
Wave must be connected in the dashboard with an Aggregated Merchant ID. If it is missing, the API returns 400 with Wave provider not configured for this organization (missing Aggregated Merchant ID).
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": "Jane Doe",
"email": "customer@example.com",
"phoneNumber": "+2250707070707"
},
"successUrl": "https://example.com/success",
"errorUrl": "https://example.com/error"
}'See Charges API and Direct charges.
Test vs live
| Test | Live | |
|---|---|---|
| Balance credit | Often when session/charge is created | After customer approves in Wave |
| Status | Usually completed quickly | Starts pending |
In live mode, never fulfill on redirect alone. See Verify payments.
Payouts
Wave beneficiary payouts require a live key and valid recipient phone. Wave self-withdrawals are live-only-test keys return 400 for Wave payout rails. See Sandbox payouts.