Embed checkout widget
Embed lomi. hosted checkout on your site with @lomi./embed, modal overlay or inline iframe.
Embed checkout widget
Keep customers on your site while they pay on lomi.'s hosted checkout page inside an iframe. Use modal for a pay button overlay, or inline to embed checkout in a product page.
Embed is best when you want the full lomi. checkout UI (Wave, MTN, cards, coupons) without a redirect. For custom card fields inside your own form, see lomi. Payment Elements.
When to use embed vs redirect vs Payment Elements
| Approach | Best for |
|---|---|
| Redirect (hosted checkout) | Simplest integration; customer leaves your site briefly |
| Embed (this guide) | Same checkout UI, stays on your page |
| Payment Elements | You own the UI; collect cards or mobile money in your layout |
Step 1: Create a checkout session
Your server creates the session and returns checkout_url to the browser.
curl
curl -sS -X POST "https://sandbox.api.lomi.africa/checkout-sessions" \
-H "X-API-Key: $LOMI_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"currency_code": "XOF",
"success_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel"
}'TypeScript SDK
import { lomiApi } from './lib/lomi/client';
const session = await lomiApi.createCheckoutSession({
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/cancel',
amount: 10000,
currency_code: 'XOF',
});
// Pass session.checkout_url to the embed SDKCLI
lomi checkout createThe CLI prints the redirect URL and a ready-to-paste embed snippet.
Step 2: Install @lomi./embed
npm install @lomi./embedModal example (bundler)
<button id="pay">Pay now</button>
<script type="module">
import { loadLomiCheckout } from '@lomi./embed';
document.getElementById('pay').addEventListener('click', () => {
loadLomiCheckout({
checkoutUrl: 'CHECKOUT_URL_FROM_YOUR_SERVER',
mode: 'modal',
onComplete: (payload) => {
console.log('Paid:', payload.transactionId);
},
});
});
</script>The SDK adds embedded=true and embed_origin automatically, do not append them to checkoutUrl.
Inline example
<div
id="lomi-checkout"
data-lomi-checkout-url="CHECKOUT_URL_FROM_YOUR_SERVER"
></div>
<script type="module">
import '@lomi./embed';
</script>Declarative attributes:
| Attribute | Description |
|---|---|
data-lomi-checkout-url | Preferred, full URL from API or payment link |
data-lomi-session-id | Alternative with data-lomi-checkout-base-url |
data-lomi-public-key | Optional when using checkoutUrl |
id | Required container id (e.g. lomi-checkout) |
Self-hosted script (no CDN)
There is no hosted CDN. Copy the IIFE bundle from the package:
cp node_modules/@lomi./embed/dist/lomi.js public/assets/lomi.js<script src="/assets/lomi.js"></script>
<script>
window.Lomi.loadLomiCheckout({
checkoutUrl: 'CHECKOUT_URL_FROM_YOUR_SERVER',
mode: 'modal',
onComplete: (p) => console.log(p),
});
</script>Payment links on checkout.lomi.africa work the same way, pass the link URL as checkoutUrl.
Callbacks and events
| Callback | When |
|---|---|
onComplete | Payment succeeded (after fulfillment when applicable) |
onResize | Iframe height changed (inline mode) |
onError | Checkout reported an error |
The iframe sends LOMI_CHECKOUT messages; legacy types LOMI_CHECKOUT_COMPLETE and LOMI_RESIZE are supported. Messages from origins other than the checkout host are ignored.
onComplete payload:
{
type: 'LOMI_CHECKOUT_COMPLETE';
sessionId?: string;
transactionId?: string;
amount?: number;
currency?: string;
hasDigitalDeliverables?: boolean;
}Webhooks
Embed callbacks improve UX only. Always reconcile orders with webhooks or a server-side API read before fulfilling.
Sandbox testing
Use sandbox API keys and pass a sandbox checkout_url. For local development, point at your checkout app:
loadLomiCheckout({
checkoutUrl: 'http://localhost:3000/checkout/cs_test_...',
mode: 'modal',
});See Sandbox payments for test payment methods.
Related
- Hosted checkout: redirect flow
- Payment links: shareable URLs (also work as
checkoutUrl) - SDKs overview:
@lomi./sdkand@lomi./embed - Package README,
node_modules/@lomi./embed/README.md
How do I use hosted checkout?
Create a checkout session, redirect the customer to lomi., then confirm the result with redirects, dashboard records, and webhooks.
How do payment links work?
Create reusable or one-time payment URLs that customers can open from email, chat, invoices, QR codes, and social channels.