Webhooks

Settlement deliveries from your tests. Open an event to read the payload.

Event timeline

// Select an event

Operating model

Status checks & callbacks

Every product uses the same reliability pattern: push when the platform notifies you, pull when you query the latest state. Implement both before go-live.

Initiate

Create payment (engine, portal, airtime, or disbursement). Capture every reference returned.

Pending

Customer completes USSD/bank/checkout or voucher flow.

Push (callback)

Platform or engine notifies your endpoint with settlement payload.

Pull (status)

Your backend queries status or getPayments if callback is late or ambiguous.

Fulfill

Mark order paid only when references match and amount/status are consistent.

Product matrix

Product	Initiate	Pull (status)	Push (callback)	Key reference
LipaPay Ver2	Engine pay, MNO/bank collection, or hosted checkout	Pull After login — on-demand reconciliation when a callback is delayed or missing.	Push Simulates LipaPay engine settlement; updates in-memory txn then visible via status.	`reference (engine)` `controlNumber (portal MNO/bank)` `external_reference (secure)`
LipaAirtime	Airtime voucher purchase or wallet recharge	Pull Wallet balance and profile pull — use callbackUrl to confirm recharge by controlNumber.	Push Matches production Lipa_Airtime callbackUrl — marks pending recharge successful.	`controlNumber`
Lipa Collection	MNO, bank, or hosted checkout collection	Pull Pull collection outcome when the callback is delayed.	Push Sandbox engine settlement for MNO/bank collections.	`controlNumber` `external_reference` `payment_url`
LipaDisbursement	Wallet payout to recipient mobile	Pull Pull model: list historical payouts for reconciliation (no push callback in sandbox).	List/history only Use getPayments and payment response txnid/refid in production integrations.	`txnid` `refid (in response JSON)`

Best practices

Treat callbacks as the primary signal, but never as the only source of truth — always support a status or list pull for recovery.
Make callback handlers idempotent: the same controlNumber or paymentReference may be delivered more than once.
Persist merchant reference, platform control number, and engine paymentReference in separate columns before calling fulfill logic.
Respond with HTTP 200 quickly on callbacks; perform heavy work asynchronously in your system.
For LipaPay engine callback, validate the full nested data.* payload — sandbox returns 422 with field errors when incomplete.
For secure checkout, verify amount and external_reference on your server when the browser hits callback_url, not only in the browser.

Sign in to inspect deliveries and run testers

Webhook testers and API contracts stay inside the KYC-registered merchant workspace.