# lomi.

> Francophone West Africa's payment platform: Mobile Money (Wave, MTN, SPI), cards (Visa, Mastercard, Apple Pay, Google Pay), bank transfers across eight UEMOA markets. Use this file as a **map**—then read the linked pages for schemas and examples.

## How to use this briefing

1. Read **Authentication** and **Integration quickstart** below.
2. Pick one **Payment flow** that matches your product (hosted checkout, links, direct charge, subscriptions, or payouts).
3. Use the [REST API hub](https://docs.lomi.africa/api/index) for Try-it and samples; treat `apps/docs/openapi.json` in the monorepo as the machine-readable contract.

## Integration quickstart

1. Create a merchant account and API keys in the [dashboard](https://dashboard.lomi.africa).
2. Build against **sandbox** first (`https://sandbox.api.lomi.africa`), then switch to **live** (`https://api.lomi.africa`) with live keys.
3. Follow the [integration overview](https://docs.lomi.africa/reference/setup/integration) for headers, environments, and product choices.
4. If you have not already, see [Getting started](https://docs.lomi.africa/core/fundamentals/create-account).

## Authentication and environments

Send the merchant **API key** on every server-side call: header `X-API-KEY`. Sandbox and live keys are different; using the wrong key against an environment returns **401**.

- **Sandbox base URL**: `https://sandbox.api.lomi.africa`
- **Live base URL**: `https://api.lomi.africa`

## Idempotency, errors, and retries

Errors use the standard JSON shape with an HTTP status and a machine-readable message.
**401** usually means a missing/invalid key; **404** means the resource does not exist for this API key; **429** means rate limiting.
For **creates** that must not double-charge (payments, payouts), send an idempotency key when your client or gateway supports it.

## Payment flows (pick one)

Choose the path that matches your UX—not every merchant needs every API.

- **Hosted checkout** — buyer completes payment on the hosted experience: [Create checkout session](https://docs.lomi.africa/api/checkout-sessions/CheckoutSessionsController_create).
- **Shareable payment links** → [Create payment link](https://docs.lomi.africa/api/payment-links/PaymentLinksController_create).
- **Direct mobile-money charge (server-initiated)** → [Create direct mobile-money charge](https://docs.lomi.africa/api/charge/ChargesController_createWaveCharge) when you are not using hosted checkout.
- **Card PaymentIntent / Elements-style** → [Create card PaymentIntent](https://docs.lomi.africa/api/payment-intents/PaymentIntentsController_create).
- **Payment request (invoice-style)** → [Create payment request](https://docs.lomi.africa/api/payment-requests/PaymentRequestsController_create).
- **Subscriptions** → explore [Cancel subscription](https://docs.lomi.africa/api/subscriptions/SubscriptionsController_cancel) (list, cancel, per-customer).
- **Payouts to your wallet** → [Initiate mobile-money payout](https://docs.lomi.africa/api/payout/PayoutsController_createWavePayout).
- **Third-party beneficiary payouts** → [Create beneficiary payout](https://docs.lomi.africa/api/beneficiary-payouts/BeneficiaryPayoutsController_create).
- **Outbound webhooks (events to your server)** → [List webhooks](https://docs.lomi.africa/api/webhooks/WebhooksController_findAll) and delivery logs under the same API section.

## REST API by domain

Each item links into the generated endpoint pages for that resource group. Primary hub: [REST API](https://docs.lomi.africa/api/index).

- **Accounts**: [Check available balance](https://docs.lomi.africa/api/accounts/AccountsController_checkAvailableBalance)
- **Beneficiary Payouts**: [Create beneficiary payout](https://docs.lomi.africa/api/beneficiary-payouts/BeneficiaryPayoutsController_create)
- **Charge**: [Create direct mobile-money charge](https://docs.lomi.africa/api/charge/ChargesController_createWaveCharge)
- **Checkout Sessions**: [Create checkout session](https://docs.lomi.africa/api/checkout-sessions/CheckoutSessionsController_create)
- **Customers**: [Create a customer](https://docs.lomi.africa/api/customers/CustomersController_create)
- **Discount Coupons**: [Create discount coupon](https://docs.lomi.africa/api/discount-coupons/DiscountCouponsController_create)
- **Organizations**: [List organizations](https://docs.lomi.africa/api/organizations/OrganizationsController_findAll)
- **Payment Intents**: [Create card PaymentIntent](https://docs.lomi.africa/api/payment-intents/PaymentIntentsController_create)
- **Payment Links**: [Create payment link](https://docs.lomi.africa/api/payment-links/PaymentLinksController_create)
- **Payment Requests**: [Create payment request](https://docs.lomi.africa/api/payment-requests/PaymentRequestsController_create)
- **Payout**: [Initiate mobile-money payout](https://docs.lomi.africa/api/payout/PayoutsController_createWavePayout)
- **Products**: [Add product price](https://docs.lomi.africa/api/products/ProductsController_addPrice)
- **Refund**: [Initiate refund](https://docs.lomi.africa/api/refund/RefundsController_createWaveRefund)
- **Subscriptions**: [Cancel subscription](https://docs.lomi.africa/api/subscriptions/SubscriptionsController_cancel)
- **Transactions**: [List transactions](https://docs.lomi.africa/api/transactions/TransactionsController_findAll)
- **Webhook Delivery Logs**: [List webhook delivery logs](https://docs.lomi.africa/api/webhook-delivery-logs/WebhookDeliveryLogsController_findAll)
- **Webhooks**: [List webhooks](https://docs.lomi.africa/api/webhooks/WebhooksController_findAll)

## Guides to read next

- [What is lomi.?](https://docs.lomi.africa/core/introduction/what-is-lomi)
- [Payment state machine](https://docs.lomi.africa/reference/reference/payment-state-machine) — status transitions and balances
- [MCP integration](https://docs.lomi.africa/reference/integrations/mcp)

## Document map (browse by section)

Prefer section sidebars on the docs site for exhaustive lists. High-level areas:

### core
- [CI/CD](https://docs.lomi.africa/core/advanced-guides/ci-cd) — This guide covers best practices for integrating lomi. with your CI/CD pipeline, ensuring reliable deployments and automated testing.
- [Error handling](https://docs.lomi.africa/core/advanced-guides/error-handling) — When integrating with lomi., it's essential to handle errors gracefully to provide a smooth payment experience for your customers.
- [Handling webhooks](https://docs.lomi.africa/core/advanced-guides/handling-webhooks) — Webhooks provide real-time updates about events in your lomi. account. This guide explains how to securely receive and process these notifications.
- [Idempotency keys](https://docs.lomi.africa/core/advanced-guides/idempotency-keys) — Idempotency ensures that an API request, if retried due to a network error or timeout, won't accidentally be performed multiple times. This is crucial for operations like creating payments or refunds to prevent duplicate actions. 
_…and 33 more pages in this section (see docs sidebar)._

### reference
- [Changelog](https://docs.lomi.africa/reference/changelog/changelog) — This page documents notable changes to the lomi. API and related services.
- [E‑commerce extensions](https://docs.lomi.africa/reference/integrations) — Official and maintained plugins for hosted checkout with Lomi. WooCommerce, Magento 2, and PrestaShop use the same public API contract; Shopify is documented separately.
- [Magento 2](https://docs.lomi.africa/reference/integrations/magento) — Lomi_Payments module — hosted checkout via checkout sessions, callback route, signed webhooks, optional REST verify.
- [MCP integration](https://docs.lomi.africa/reference/integrations/mcp) — Connect your AI client to Lomi with the Model Context Protocol.
_…and 41 more pages in this section (see docs sidebar)._

### api
- [Check available balance](https://docs.lomi.africa/api/accounts/AccountsController_checkAvailableBalance) — Check available balance
- [List accounts](https://docs.lomi.africa/api/accounts/AccountsController_findAll) — List accounts
- [Retrieve an account](https://docs.lomi.africa/api/accounts/AccountsController_findOne) — Retrieve an account
- [Account balances](https://docs.lomi.africa/api/accounts/AccountsController_getBalance) — Account balances
_…and 46 more pages in this section (see docs sidebar)._

## Contact and support

- Website: https://lomi.africa
- Documentation: https://docs.lomi.africa
- Email: hello@lomi.africa
- GitHub: https://github.com/lomiafrica/lomi./
- Discord: https://discord.gg/33syDfh9
- X: https://twitter.com/lomiafrica

## Common questions

**Where do schemas live?** Use the [REST API](https://docs.lomi.africa/api/index) explorer and the OpenAPI export at `apps/docs/openapi.json` (generated from `apps/api`).
**How do I reconcile payments?** Start from [List transactions](https://docs.lomi.africa/api/transactions/TransactionsController_findAll) and tie provider references to your internal order IDs using metadata on creates.