# lomi.

> Payment infrastructure for francophone West Africa: hosted checkout, Mobile Money, cards, payouts, subscriptions, and developer APIs across UEMOA. Use this file as a **map**: then read the linked pages for schemas and examples.

## When to use lomi.

- Accept Wave, MTN, SPI, cards, and other local payment methods through one integration.
- Send customers to hosted checkout instead of building payment collection from scratch.
- Create payment links for invoices, services, events, donations, or product sales.
- Run recurring payments and customer subscriptions.
- Receive webhooks for payments, refunds, subscriptions, and checkout states.
- Track balances, transactions, refunds, and payouts from the merchant dashboard.

## UEMOA / Mobile Money (integrator facts)

- Primary market: UEMOA (francophone West Africa).
- Mobile money rails include Wave and MTN; SPI connects 64+ mobile money operators and banks.
- Live mobile-money payments are asynchronous: confirm final status via webhooks and GET /transactions/{id}.
- Amounts in XOF use integer centimes (minor units) unless a field documents otherwise.
- API keys: lomi_sk_test_* (sandbox) and lomi_sk_live_* (live); the key selects environment, not the hostname alone.

## Disambiguation

- **Canonical name:** lomi.
- Not related to similarly-named products, places, or brands in other industries.

## Agent corpus (plain text)

Machine-readable pages for crawlers and agents (not linked from the docs navigation):
- https://docs.lomi.africa/agents
- https://docs.lomi.africa/agents/product
- https://docs.lomi.africa/agents/limits
- https://docs.lomi.africa/agents/uemoa-mobile-money
- https://docs.lomi.africa/agents/integration
- https://docs.lomi.africa/agents/mcp
- https://docs.lomi.africa/agents/compare
- https://docs.lomi.africa/agents/faq
- https://docs.lomi.africa/agents/disambiguation

## 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, usage billing, or payouts).
3. Use the [API hub](https://docs.lomi.africa/api) for Try-it and samples; treat `apps/docs/openapi.json` in the monorepo as the machine-readable contract.

## Integration quickstart

- **Amounts (XOF):** integer **centimes** (minor units) unless a field documents otherwise.
- **Keys:** `lomi_sk_test_…` / `lomi_sk_live_…`, the **API key selects sandbox vs live**, not the hostname alone.
- **Verify server-side before fulfill:** never trust client-only success; use webhooks + `GET /transactions/{id}`.

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. **Default integration path:** hosted checkout sessions or payment links before direct `/charge/*` calls unless you need a custom server-initiated flow.
4. **Environment is determined by the API key**, not the hostname alone; sandbox keys only work against sandbox; live keys only against live.
5. **Mobile money (live) is asynchronous:** the customer approves on device; confirm final status via webhooks and `GET /transactions/{id}` before fulfilling.
6. Follow the [integration journey](https://docs.lomi.africa/start/integration-journey) for sandbox → webhooks → go-live.
- [How do I verify a payment?](https://docs.lomi.africa/build/reliability/verify-payments), confirm status before fulfilling.
- [Payment and payout lifecycle](https://docs.lomi.africa/build/reliability/payment-lifecycle), merchant-facing lifecycle hub.
- Supported countries and rails: [Which payment methods?](https://docs.lomi.africa/build/payment-channels).
- Test cards and MoMo sandbox behavior: [How do I test in sandbox?](https://docs.lomi.africa/start/sandbox-payments).

## Markets

Coverage map. Details: [Payment channels](https://docs.lomi.africa/build/payment-channels).

- **Côte d'Ivoire, Senegal, and UEMOA:** Wave (`XOF`), cards, and SPI on hosted checkout.
- **MTN:** CI plus CM, GH, UG, ZM, BJ, CG, SZ, GN, ZA, LR, NG.
- **Not lomi. rails:** Orange Money and Apple Pay. Djamo is coming for CI and SN.

## 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**. **The key determines sandbox vs live; not the request URL alone.**

- **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. **Prefer hosted checkout or payment links** unless you need direct charges.

**MCP checkout (agents):** 1. `lomi_checkout action=create` and persist `id` plus `checkout_url`. 2. Send the customer `checkout_url`. 3. Create a webhook (`lomi_webhooks action=create`) and persist the signing secret. 4. After the webhook, confirm with `lomi_transactions action=get` before fulfilling. Guest bootstrap without a key: connect `https://mcp.lomi.africa/mcp/guest`, call `lomi_register_agent`, then `lomi_provision action=create_account` → `upload_document` → `complete` → `api_keys`; once a `lomi_sk_test_*` key is returned the same session gains the merchant tools (`notifications/tools/list_changed`), no reconnect. Humans with an account use the one-click OAuth buttons on `https://mcp.lomi.africa/mcp` instead. Live still needs `lomi_provision action=request_live` and human approval at https://dashboard.lomi.africa/connect/go-live.

- **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.
- **Embedded card charge (lomi. Elements)** → [Create embedded card charge](https://docs.lomi.africa/api/charge/ChargesController_createCardCharge) (`POST /charge/card` returns `client_secret`; confirm with `loadLomi('lomi_pk_…')`).
- **Payment request (invoice-style)** → [Create payment request](https://docs.lomi.africa/api/payment-requests/PaymentRequestsController_create).
- **Subscriptions** → explore [Subscriptions](https://docs.lomi.africa/api/subscriptions) (list, cancel, per-customer).
- **Usage billing (prepaid packs)** → [Usage billing](https://docs.lomi.africa/build/billing/usage-billing): pack checkout on card, Wave, or MTN, then events spend the units ([Create meter](https://docs.lomi.africa/api/meters/MetersController_create)).
- **Payouts (self wallet or third-party beneficiaries)** → [Create payout](https://docs.lomi.africa/api/payouts/PayoutsUnifiedController_create).
- **Outbound webhooks (events to your server)** → [Webhooks](https://docs.lomi.africa/api/webhooks) and delivery logs under the same API section.

## API by domain

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

- **Checkout Sessions**: [Create checkout session](https://docs.lomi.africa/api/checkout-sessions/CheckoutSessionsController_create)
- **Payment Links**: [Archive payment link](https://docs.lomi.africa/api/payment-links/PaymentLinksController_archive)
- **Whatsapp**: [Create WhatsApp setup link](https://docs.lomi.africa/api/whatsapp/WhatsAppMerchantController_createSetupLink)
- **Payment Requests**: [Create payment request](https://docs.lomi.africa/api/payment-requests/PaymentRequestsController_create)
- **Invoices**: [Créer une facture](https://docs.lomi.africa/api/invoices/InvoicesController_create)
- **Charge**: [Advanced direct charges](https://docs.lomi.africa/api/charge)
- **Customers**: [Block a customer](https://docs.lomi.africa/api/customers/CustomersController_block)
- **Products**: [Add product price](https://docs.lomi.africa/api/products/ProductsController_addPrice)
- **Subscriptions**: [Subscriptions](https://docs.lomi.africa/api/subscriptions)
- **Coupons**: [Create discount coupon](https://docs.lomi.africa/api/coupons/DiscountCouponsController_create)
- **Balances**: [Balances](https://docs.lomi.africa/api/balances)
- **Transactions**: [List transactions](https://docs.lomi.africa/api/transactions/TransactionsController_findAll)
- **Refunds**: [Create refund](https://docs.lomi.africa/api/refunds/RefundsController_create)
- **Transfers**: [Create transfer](https://docs.lomi.africa/api/transfers/TransfersController_create)
- **Payouts**: [Create payout](https://docs.lomi.africa/api/payouts/PayoutsUnifiedController_create)
- **Payout Methods**: [Add a payout method](https://docs.lomi.africa/api/payout-methods/PayoutMethodsController_create)
- **Settlements**: [Request an instant settlement (Nitro)](https://docs.lomi.africa/api/settlements/SettlementsController_createInstant)
- **Organizations**: [Create organization](https://docs.lomi.africa/api/organizations/OrganizationsController_create)
- **Network**: [Create account session](https://docs.lomi.africa/api/network/NetworkAccountsController_createAccountSession)
- **Team**: [Invite team member](https://docs.lomi.africa/api/team/TeamController_invite)
- **Settings**: [Get checkout settings](https://docs.lomi.africa/api/settings/SettingsController_getCheckout)
- **Merchants**: [Get merchant ARR](https://docs.lomi.africa/api/merchants/MerchantsController_getArr)
- **Providers**: [List payment providers](https://docs.lomi.africa/api/providers/ProvidersController_findAll)
- **Disputes**: [List disputes](https://docs.lomi.africa/api/disputes/DisputesController_findAll)
- **Support Requests**: [Close support ticket](https://docs.lomi.africa/api/support-requests/SupportRequestsController_close)
- **Risk Assessments**: [Get risk assessment](https://docs.lomi.africa/api/risk-assessments/RadarController_findOne)
- **Webhooks**: [Webhooks](https://docs.lomi.africa/api/webhooks)
- **Logs**: [List logs](https://docs.lomi.africa/api/logs/LogsController_findAll)
- **Meters**: [Create a meter](https://docs.lomi.africa/api/meters/MetersController_create)
- **Usage**: [Check customer entitlement](https://docs.lomi.africa/api/usage/UsageBillingController_checkEntitlement)
- **Exports**: [Create an export job](https://docs.lomi.africa/api/exports/MerchantExportsController_create)
- **Finance**: [Receivables aging buckets](https://docs.lomi.africa/api/finance/FinanceController_aging)
- **Api Keys**: [Create API key](https://docs.lomi.africa/api/api-keys/ApiKeysController_create)
- **Account**: [Delete merchant account](https://docs.lomi.africa/api/account/AccountController_deleteAccount)

## Agent onboarding & MCP OAuth

Agents can onboard **new merchants** (0→1) via MCP provisioning tools or the `/provisioning/*` API. Full guide: [MCP for AI clients](https://docs.lomi.africa/build/mcp). Machine contract: `apps/docs/agent-openapi.json` (provisioning + partner routes). Optional marketplace install: [lomiafrica/agent-plugin](https://github.com/lomiafrica/agent-plugin); the hosted MCP URL works without the plugin.

**Credential types:**

- **`lomi_partner_*`**, platform management key (issued by lomi admin). Mint per-user `lomi_prov_*` via Partner API.
- **`lomi_prov_*`**, provisioning key for `/provisioning/*` and MCP 0→1 tools (`x-lomi-provisioning-key`).
- **`lomi_oat_*`**, OAuth access token from MCP authorization; MCP introspects it to a scoped `lomi_prov_*` session.

**Partner API** (header `x-lomi-partner-key` or `Authorization: Bearer lomi_partner_*`):

- `POST /partners/provisioning-keys`, mint scoped `lomi_prov_*` for `external_user_ref`
- `GET /partners/provisioning-keys`, list keys
- `DELETE /partners/provisioning-keys/{id}`, revoke
- `GET /partners/usage`, usage summary

**OAuth self-service** (MCP clients with authorization support):

1. `GET https://mcp.lomi.africa/.well-known/oauth-protected-resource/mcp`
2. `POST https://api.lomi.africa/oauth/register` (optional DCR)
3. `GET https://api.lomi.africa/oauth/authorize` (PKCE + `resource`) → user approves at `https://dashboard.lomi.africa/connect/agent-connect`
4. `POST https://api.lomi.africa/oauth/token` → `lomi_oat_*`
5. Connect MCP with `Authorization: Bearer <access_token>`; session auto-adopts merchant `lomi_sk_test_*` after onboarding completes.

**Two entry points, one product:** humans with (or wanting) a lomi. account use the one-click OAuth buttons; the consent page signs in or signs up, then resumes approval. Agents with no account use `https://mcp.lomi.africa/mcp/guest` + `lomi_register_agent`; the guest session upgrades to test merchant tools in place once `lomi_provision action=api_keys` returns a key. Live keys are dashboard-only.

**Human claim link:** `POST /provisioning/accounts` without `password` returns `claim_url` (dashboard `/connect/claim?token=`, 7 days, single use). Send this link to the human; they set their own password and own the account. `GET .../onboarding/status` reports `human_claimed` and re-issues `claim_url` until true. Live approval requires a claimed account.

**Test → live (human-gated):**

- `POST /provisioning/merchants/{id}/live-activation/request`, agent requests go-live; share `merchant_approval_path` with the human merchant.
- `GET /provisioning/merchants/{id}/live-activation/status`, poll until approved (`live_keys_available` means merchant can retrieve live key on dashboard).
- Merchant approves at `https://dashboard.lomi.africa/connect/go-live` and retrieves `lomi_sk_*` live secret (never via provisioning API). Starter: AI KYC review; registered: admin approval.

- [MCP for AI clients](https://docs.lomi.africa/build/mcp), tools, prompts, hosted server config

## Guides to read next

- [What is lomi.?](https://docs.lomi.africa/start/overview)
- [Integration journey](https://docs.lomi.africa/start/integration-journey)
- [How do I verify a payment?](https://docs.lomi.africa/build/reliability/verify-payments)
- [Payment and payout lifecycle](https://docs.lomi.africa/build/reliability/payment-lifecycle)
- [Which payment methods?](https://docs.lomi.africa/build/payment-channels)
- [MCP for AI clients](https://docs.lomi.africa/build/mcp)
- [How do I use checkout?](https://docs.lomi.africa/build/accept/checkout), REST / MCP / CLI / SDK for the same job

## Document map (browse by section)

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

### start
- [Where are my API keys?](https://docs.lomi.africa/start/api-keys), Find your test and live keys, understand which key belongs where, and store them safely.
- [Get started with the CLI](https://docs.lomi.africa/start/cli-quickstart), Install lomi. CLI, log in, run quickstart checks, create a test checkout, and forward webhooks locally.
- [How do I create an account?](https://docs.lomi.africa/start/create-account), Create your dashboard account, choose the right verification path, and prepare your business to accept test and live payments.
- [How do I test a payment?](https://docs.lomi.africa/start/first-payment), Create a sandbox checkout session, open the hosted checkout URL, pay with a test method, and verify the result.
_…and 10 more pages in this section (see docs sidebar)._

### build
- [Which integration to choose?](https://docs.lomi.africa/build/choose-integration), Choose between hosted checkout, payment links, payment requests, direct charges, subscriptions, and ecommerce extensions.
- [How to accept mobile money?](https://docs.lomi.africa/build/mobile-money), Hosted checkout, payment links, or direct charges.
- [Which payment methods?](https://docs.lomi.africa/build/payment-channels), Country, currency, and channel matrix for hosted checkout and direct charges in francophone West Africa and MTN markets.
- [How do I place a card hold?](https://docs.lomi.africa/build/accept/card-holds), Block a deposit on a card, then capture part of it or release the rest.
_…and 69 more pages in this section (see docs sidebar)._

### api
- [Authentication](https://docs.lomi.africa/api/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](https://docs.lomi.africa/api/data-models), Common objects returned by the public lomi. API, with the fields integrators usually need to understand first.
- [Error handling](https://docs.lomi.africa/api/errors), Understanding and handling API error responses.
- [Overview](https://docs.lomi.africa/api), Use the public lomi. merchant API to accept payments, manage commerce objects, move money, and handle operational events.
_…and 161 more pages in this section (see docs sidebar)._

### resources
- [Community](https://docs.lomi.africa/resources/community), We believe that the best products are built together with users' and contributors' input. In our case, our growth and evolution are essentially driven by real merchant performance and needs.
- [Manifesto](https://docs.lomi.africa/resources/manifesto), The time has come to open-source payment processing (and software in general) across Africa.
- [Open source](https://docs.lomi.africa/resources/open-source), lomi. publishes integrator tooling and documentation as open source. Payment processing runs on our hosted platform, not as a self-hosted product today.
- [API reference authoring](https://docs.lomi.africa/resources/contributing/api-reference-authoring), How we maintain the hand-written API section, keep it aligned with OpenAPI, and avoid accidental destructive generation.
_…and 10 more pages in this section (see docs sidebar)._

## Contact and support

- Website: https://lomi.africa
- Documentation: https://docs.lomi.africa/start/overview
- 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 [API](https://docs.lomi.africa/api) 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.