How do I verify a payment before fulfilling?

A customer may close the browser, lose network connectivity, or return to your success_url before lomi. has finished processing, especially with mobile money and 3D Secure cards. Treat the redirect as a UX hint, not proof of payment.

Never fulfill on redirect alone

Do not ship goods, unlock content, or mark an invoice paid based only on success_url query parameters or client-side JavaScript. Always verify on your server.

Recommended verification order

Webhook: lomi. POSTs to your HTTPS endpoint when the transaction reaches a final state (preferred for async rails).
API read: GET /transactions/{id} or list with filters when you have the transaction ID from the checkout session or charge response.
Dashboard: manual ops and support; not for production fulfillment automation.

Hosted checkout

After the customer pays:

Store your internal order_id in checkout session metadata when you create the session.
On success_url, show a “processing” state, not “paid”-until your backend confirms.
When you receive transaction.completed (or your configured event type), match metadata.order_id and fulfill.

See Payment state machine for status meanings and Handling webhooks for signature verification.

Direct charges (Wave, MTN, card)

Rail	When to verify
Wave (live)	After customer approves in the Wave app, webhook or poll transaction
MTN MoMo (live)	Starts `PENDING`; verify before fulfill
MTN / Wave (test)	May complete immediately; still verify server-side in integration tests
Card	After `client_secret` confirmation; watch for `requires_action`

Idempotency on fulfill

Your fulfillment handler (webhook worker or API poller) must be idempotent: processing the same transaction_id or webhook event id twice must not double-ship. Store processed event IDs or use database constraints on order_id + status = fulfilled.

Checklist

success_url shows pending until server confirms
Webhook endpoint verifies X-Lomi-Signature on the raw body
Fulfillment runs only when transaction_status is completed
Refunds and chargebacks have a reversal path