# lomi.

> Payment infrastructure for francophone West Africa: hosted checkout, Mobile Money, cards, payouts, subscriptions, and developer APIs across UEMOA.

## Product summary

- **Region:** Francophone West Africa (UEMOA): Benin, Burkina Faso, Côte d'Ivoire, Guinea-Bissau, Mali, Niger, Senegal, Togo.
- **Category:** Payment processing platform (hosted checkout, payment links, payouts, subscriptions, usage billing, invoicing).
- **Payment methods:** Mobile Money (Wave, MTN MoMo), SPI interoperability, major cards (Visa, Mastercard, Amex, GIM UEMOA), Apple Pay and Google Pay where card acquiring is enabled.
- **Core use cases:** Accept online payments, send payouts, sell subscriptions, meter usage, operate a customer portal, integrate via REST API, SDKs, CLI, Shopify/WooCommerce plugins, and MCP tools for AI agents.
- **Pricing:** Volume-based tiers with no setup or monthly fees. See https://lomi.africa/pricing
- **Security:** PCI DSS-aligned card flows; encryption and tokenization for sensitive data. See https://lomi.africa/privacy
- **Support:** hello@lomi.africa

## Official links

- Website: https://lomi.africa
- Documentation: https://docs.lomi.africa
- Dashboard: https://dashboard.lomi.africa
- API (live): https://api.lomi.africa
- API (sandbox): https://sandbox.api.lomi.africa
- OpenAPI: https://lomi.africa/openapi.json
- Agent OpenAPI: https://lomi.africa/agent-openapi.json
- Agent card: https://lomi.africa/.well-known/agent.json
- MCP server: https://mcp.lomi.africa
- Developer briefing (llms.txt): https://docs.lomi.africa/llms.txt
- Agent corpus (plain text): https://docs.lomi.africa/agents
- Full documentation corpus (llms-full.txt): https://docs.lomi.africa/llms-full.txt

## Entity profiles (keep descriptions aligned)

- https://github.com/lomiafrica/lomi.
- https://twitter.com/lomiafrica
- https://www.linkedin.com/company/lomiafrica
- https://www.crunchbase.com/organization/lomi-africa

---

## Developer documentation (from docs.lomi.africa)
## When to use lomi.

- Accept Wave, MTN MoMo, 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 MoMo; 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 [REST 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 before fulfilling?](https://docs.lomi.africa/build/guides/verify-payments), confirm status before fulfilling.
- [Payment and payout lifecycle](https://docs.lomi.africa/build/guides/payment-lifecycle), merchant-facing lifecycle hub.
- Supported countries and rails: [Which payment channels does lomi. support?](https://docs.lomi.africa/build/payment-channels).
- Test cards and MoMo sandbox behavior: [How do I test safely in sandbox?](https://docs.lomi.africa/start/sandbox-payments).

## 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.

- **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 (Elements-style)** → [Create embedded card charge](https://docs.lomi.africa/api/charge/ChargesController_createCardCharge) (**not available yet**: `POST /charge/card` returns `503 service_unavailable`; use [hosted checkout](/build/checkout) for cards).
- **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 (metered products)** → [Usage billing](https://docs.lomi.africa/build/usage-billing), meters, usage events, billing periods ([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.

## 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).

- **Checkout Sessions**: [Create checkout session](https://docs.lomi.africa/api/checkout-sessions/CheckoutSessionsController_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)
- **Charge**: [Advanced direct charges](https://docs.lomi.africa/api/charge)
- **Customers**: [Create a customer](https://docs.lomi.africa/api/customers/CustomersController_create)
- **Products**: [Add product price](https://docs.lomi.africa/api/products/ProductsController_addPrice)
- **Subscriptions**: [Subscriptions](https://docs.lomi.africa/api/subscriptions)
- **Discount Coupons**: [Create discount coupon](https://docs.lomi.africa/api/discount-coupons/DiscountCouponsController_create)
- **Balances**: [Balances](https://docs.lomi.africa/api/balances)
- **Organizations**: [List organizations](https://docs.lomi.africa/api/organizations/OrganizationsController_findAll)
- **Merchants**: [Get merchant ARR](https://docs.lomi.africa/api/merchants/MerchantsController_getArr)
- **Providers**: [List payment providers](https://docs.lomi.africa/api/providers/ProvidersController_findAll)
- **Transactions**: [List transactions](https://docs.lomi.africa/api/transactions/TransactionsController_findAll)
- **Refunds**: [Create refund](https://docs.lomi.africa/api/refunds/RefundsController_create)
- **Disputes**: [List disputes](https://docs.lomi.africa/api/disputes/DisputesController_findAll)
- **Risk Assessments**: [Get risk assessment](https://docs.lomi.africa/api/risk-assessments/RadarController_findOne)
- **Payouts**: [Create payout](https://docs.lomi.africa/api/payouts/PayoutsUnifiedController_create)
- **Settlements**: [List settlement periods](https://docs.lomi.africa/api/settlements/SettlementsController_findAll)
- **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 Events**: [Create a usage subscription](https://docs.lomi.africa/api/usage-events/UsageEventsController_createUsageSubscription)
- **Usage Billing**: [Check customer entitlement](https://docs.lomi.africa/api/usage-billing/UsageBillingController_checkEntitlement)

## Agent onboarding & MCP OAuth

Agents can onboard **new merchants** (0→1) via MCP provisioning tools or the `/provisioning/v1/*` REST API. Full guide: [MCP for AI clients](https://docs.lomi.africa/build/mcp). Machine contract: `apps/docs/agent-openapi.json` (provisioning + partner routes).

**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/v1/*` 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/v1/provisioning-keys`, mint scoped `lomi_prov_*` for `external_user_ref`
- `GET /partners/v1/provisioning-keys`, list keys
- `DELETE /partners/v1/provisioning-keys/{id}`, revoke
- `GET /partners/v1/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.

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

- `POST /provisioning/v1/merchants/{id}/live-activation/request`, agent requests go-live; share `merchant_approval_path` with the human merchant.
- `GET /provisioning/v1/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 before fulfilling?](https://docs.lomi.africa/build/guides/verify-payments)
- [Payment and payout lifecycle](https://docs.lomi.africa/build/guides/payment-lifecycle)
- [Which payment channels does lomi. support?](https://docs.lomi.africa/build/payment-channels)
- [Payment state machine](https://docs.lomi.africa/api/payment-state-machine), status transitions and balances
- [MCP for AI clients](https://docs.lomi.africa/build/mcp)

## Document map (browse by section)

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

### start
- [Where do I find 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 a lomi. 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 make a test 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 5 more pages in this section (see docs sidebar)._

### build
- [Balance and settlement](https://docs.lomi.africa/build/balance-and-settlement), How merchant balances, fees, and availability work after a successful payment.
- [Buy Now Pay Later (BNPL)](https://docs.lomi.africa/build/bnpl), SPI deferred debit for XOF checkout — merchant upfront payout and customer installments.
- [How do I use hosted checkout?](https://docs.lomi.africa/build/checkout), Create a checkout session, redirect the customer to lomi., then confirm the result with redirects, dashboard records, and webhooks.
- [Which payment integration should I choose?](https://docs.lomi.africa/build/choose-integration), Choose between hosted checkout, payment links, payment requests, direct charges, subscriptions, ecommerce extensions, and UI components.
_…and 78 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.
- [API reference](https://docs.lomi.africa/api), Use the public lomi. merchant API to accept payments, manage commerce objects, move money, and handle operational events.
_…and 97 more pages in this section (see docs sidebar)._

### resources
- [Changelog](https://docs.lomi.africa/resources/changelog), This page documents notable changes to lomi.. API and related services.
- [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.
- [We're here for you !](https://docs.lomi.africa/resources/support), lomi. is committed to providing exceptional support to our community and customers. We offer multiple channels for getting help, asking questions, and connecting with our team.
_…and 20 more pages in this section (see docs sidebar)._

### ui
- [Checkout summary card](https://docs.lomi.africa/ui/checkout-summary), Dark hosted-checkout product summary panel.
- [Mobile money checkout](https://docs.lomi.africa/ui/mobile-money-checkout), A specialized checkout card form for Mobile Money providers.
- [Payment provider selector](https://docs.lomi.africa/ui/payment-provider), Hosted-checkout payment method carousel for Wave, MTN, cards, and SPI.
_…and 1 more pages (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) 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.