API reference
Use the public lomi. merchant API to accept payments, manage commerce objects, move money, and handle operational events.
The API reference documents the public merchant API: the endpoints a developer should use from a server-side integration. It intentionally does not expose internal provider, organization, merchant-admin, or agent services.
If you are choosing an integration path, start with Integration journey or Which payment integration should I choose?.
Base URLs
| Environment | Base URL | Secret key |
|---|---|---|
| Test | https://sandbox.api.lomi.africa | lomi_sk_test_... |
| Live | https://api.lomi.africa | lomi_sk_live_... |
Send your secret key in the X-API-Key header from your server.
Accept payments
| Goal | API |
|---|---|
| Hosted checkout | Checkout sessions |
| Shareable payment URLs | Payment links |
| Backend-created payment requests | Payment requests |
| Lower-level Wave, MTN MoMo, and card flows | Advanced direct charges |
Manage commerce
| Goal | API |
|---|---|
| Customer records and portal launch sessions | Customers |
| Products, prices, and catalogs | Products |
| Recurring billing and customer subscriptions | Subscriptions |
| Discount codes and coupon performance | Discount coupons |
Move and reconcile money
| Goal | API |
|---|---|
| Read available and pending balances | Balances |
| Inspect payment records | Transactions |
| Create and inspect refunds | Refunds |
| Create and inspect payouts | Payouts |
Operate reliably
| Goal | API |
|---|---|
| Configure endpoints, test delivery, inspect logs, retry failures | Webhooks |
Reference conventions
- Guide pages explain product decisions and end-to-end flows.
- API pages describe exact HTTP operations.
- Direct charges are advanced; hosted checkout remains the default recommendation.
- Use sandbox for development and live only after your integration passes the go-live checklist.
Authentication
All lomi. requests are authenticated using API keys. Any request that doesn't include a valid API key will return an authentication error.
Data models
Common objects returned by the public lomi. API, with the fields integrators usually need to understand first.
Error handling
Understanding and handling API error responses.
Payment state machine
How transaction and provider statuses transition, expire, and map to balances.