# 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, 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 methods does lomi. support?](https://docs.lomi.africa/build/guides/payment-methods).
- 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).
- **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)
- **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)

## 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 methods does lomi. support?](https://docs.lomi.africa/build/guides/payment-methods)
- [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 4 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.
- [How do I accept card payments?](https://docs.lomi.africa/build/cards) — Choose hosted checkout for most card flows, or embedded card collection when your app needs full UI control.
- [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 76 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 98 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 19 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.