lomi Payment Integration Reference (SDK-first)

This is a standalone reference app that demonstrates the same checkout + webhook flow as the raw API example, but with official SDKs:

• Backend session creation: @lomi./sdk
• Frontend embed helper (optional): @lomi./embed

It is isolated in its own folder and does not require changes in other apps.

Why this version exists

Use this when you want:

• Better DX and maintainability with SDK abstractions
• Fewer raw HTTP details in application code
• A clean template for production-like app code

Keep the raw API reference when you want transparent HTTP examples and language-agnostic docs.

Quick start

From this directory:

pnpm install
cp .env.example .env
pnpm run dev

Then open:

• http://localhost:3001

Health check:

curl -s http://localhost:3001/api/health

Required environment variables

LOMI_BASE_URL=https://api.lomi.africa
LOMI_API_KEY=your-lomi-api-key
LOMI_WEBHOOK_VERIFICATION_TOKEN=your-webhook-verification-token
LOMI_PUBLIC_KEY=lomi_pk_your_publishable_key

Notes:

• LOMI_API_KEY is required on server to create checkout sessions.
• LOMI_PUBLIC_KEY is used by the browser embed SDK demo button.

What this app demonstrates

Server (server/index.js)

• Creates checkout sessions using LomiSDK (sdk.checkoutSessions.create(...))
• Supports dynamic amount, price-based, and line-items routes
• Verifies webhooks with HMAC SHA256 via X-Lomi-Signature
• Serves a local browser bundle path for @lomi./embed:
  • /vendor/lomi-embed.js

Frontend (frontend/main.js)

• Calls local server routes for checkout session creation
• Opens hosted checkout in a new tab
• Embeds hosted checkout in an iframe
• Uses loadLomiCheckout(...) from @lomi./embed for modal embed

API routes

• GET /api/health
• GET /api/config
• POST /api/checkout/dynamic
• POST /api/checkout/price
• POST /api/checkout/line-items
• POST /api/webhooks/lomi
• GET /api/webhooks/events

Recommended next improvements

• Persist webhook events in a DB and dedupe by event ID
• Add request validation middleware
• Add tests for webhook signature verification and checkout payload validation