Integration journey

Follow this guide before you write production code. Each step links to the detailed page, this page is the map, not the manual.

New here? Start with What is lomi.?, then follow this journey step by step.

Step 1: Create a developer account

Sign up for a lomi. account to access the test environment, where you can run full payment flows without moving real money.

In test mode you can:

Accept payments using test card numbers and simulated mobile money.
Create checkout sessions, payment links, and direct charges against the sandbox API.
Receive webhooks with "environment": "test" on payloads.

See Create your account and API keys.

Step 2: Choose your integration

lomi. supports multiple integration options depending on your stack:

If you need	Start with
A complete checkout page	Hosted checkout
Checkout embedded on your site	Embed checkout widget
A shareable URL	Payment links
A backend-created payment request	Payment requests
Server-initiated mobile money or embedded cards	Direct charges
Recurring billing	Subscriptions via checkout or links
Store plugin (WooCommerce, Shopify, etc.)	E-commerce extensions

Define what you sell in Products before you create checkout sessions or subscription plans.

Most teams should start with hosted checkout. Use Which payment integration should I choose? and Payment channels to confirm Wave, MTN, and card coverage for your markets.

Step 3: Test end-to-end

Test your integration thoroughly using sandbox credentials:

Make a test payment: CLI or API checkout session.
Use Sandbox payments for test cards, Wave, and MTN behavior.
Exercise failure paths with Simulate errors.
Fix issues using Error handling and Idempotency keys.
For checkout edge cases (subscriptions, trials, pending mobile money), see Checkout behavior and per-channel guides under Payment channels.

Step 4: Configure webhooks

Webhooks are especially useful for payment methods and events that happen outside your application's control, such as mobile money approval and subscription renewals.

Register an HTTPS endpoint in the dashboard.
Follow Setting up webhooks and Handling webhooks.
Verify signatures from the raw request body before you parse JSON.

Subscription renewals: Card subscriptions renew off-session; listen for SUBSCRIPTION_RENEWED and renewal PAYMENT_FAILED. Wave and MTN subscriptions use a manual renewal checkout link sent before each billing date, the customer must pay that link; there is no silent wallet debit. See Subscriptions: Renewals.

Step 5: Go live

When sandbox flows pass your checklist:

Complete account verification and payout setup.
Switch servers to lomi_sk_live_... and https://api.lomi.africa.
Run the go-live checklist and process one small live payment with webhook verification.