Official documentation

Integrate LipaPay with confidence.

This guide covers what each product does, how settlement works, and how merchants move from sandbox testing to live operations. Contracts and credentials stay inside the signed-in workspace after KYC registration.

Key highlights

Everything an integrator needs before writing a line of production code.

01

KYC before access

Sandbox is a merchant workspace, not a public playground. Registration captures business identity and a compliance document.

02

One operating model

Authenticate, initiate, wait for settlement notification, then confirm with a status pull before you fulfill the customer.

03

Sandbox then live

Test with simulated money first. After compliance approval, switch the same workspace to live for production integration.

04

Never trust a single signal

Callbacks are the primary notice. Status pulls are the source of truth when a notification is late, duplicated, or missing.

05

Four products, one platform

LipaPay, Lipa Collection, LipaAirtime, and LipaDisbursement share identity, environments, and support — not one mixed wallet.

06

Contracts stay private

This documentation explains behaviour and responsibility. Technical contracts open only after you sign in as a registered merchant.

Who this is for

Product & operations

Understand what each LipaPay product settles, what the customer experiences, and when it is safe to release goods or airtime.

Engineering leads

Scope sandbox vs live, reconciliation duties, and which team owns callbacks before implementation starts.

Compliance

See why KYC is required to open the workspace and what “approved” unlocks for live settlement.

Products

Four capabilities. Same reliability pattern. Choose the product that matches the money movement.

Engine

LipaPay

Core merchant settlement. Collect from a customer, receive confirmation, then verify status before fulfillment. Hosted checkout sits on the same model.

  • Customer pays via mobile or checkout
  • Platform notifies your system when settlement lands
  • Your backend confirms amount and reference, then fulfills

Inbound

Lipa Collection

MNO push, bank collection, and hosted checkout grouped as inbound money. Same settlement rules as LipaPay — initiate, notify, confirm.

  • Choose channel: mobile network, bank, or hosted page
  • Capture every reference returned at initiate
  • Do not mark an order paid on initiate alone

Value

LipaAirtime

Vouchers and wallet recharge. Issue airtime only after the recharge is confirmed — never on the first accept.

  • Debit or top up the merchant airtime wallet
  • Wait for confirmation of the control reference
  • Then release value to the subscriber

Outbound

LipaDisbursement

Wallet payouts to a recipient mobile. Reconciliation is a history pull, not a webhook. Store the payout reference from the accept response.

  • Send amount, name, and mobile
  • Keep the platform reference from the response
  • Reconcile later from payment history

Programme path

Integration journey

A governed path from merchant onboarding to live settlement. Each stage has an owner, an exit gate, and a business outcome — not a checklist of technical calls.

Merchant owns
LipaPay owns
Exit gate

  1. Stage 01 · Governance

    Establish the merchant

    Legal identity, operating address, intended products, and a compliance document. This is the commercial record LipaPay reviews — not a developer signup.

    • Owner Merchant applicant
    • Exit gate Complete KYC registration accepted
    • Outcome Sandbox workspace may open

  2. Stage 02 · Enable

    Activate sandbox

    Pending review is enough to test. Settlement is simulated. Operations can inspect deliveries and confirm status before any live liability exists.

    • Owner Merchant integration team
    • Exit gate Workspace credentials issued
    • Outcome Isolated test tenant ready

  3. Stage 03 · Prove

    Certify the full loop

    For every product you will launch: initiate, pending customer action, platform notification, independent confirmation, then fulfillment. Sign off only when references and amounts match.

    • Owner Engineering & operations
    • Exit gate End-to-end loop signed off
    • Outcome Ready for compliance decision

  4. Stage 04 · Assure

    Compliance decision

    LipaPay reviews the KYC file. Approval is communicated by email with production access. Rejection locks the console until a corrected submission is received.

    • Owner LipaPay compliance
    • Exit gate Approved or returned
    • Outcome Live mode eligible, or resubmit

  5. Stage 05 · Launch

    Operate in live

    Same workspace, production hosts, real money. Switch environment only after sandbox sign-off. Live tokens and sandbox tokens are never interchangeable.

    • Owner Merchant, with LipaPay support
    • Exit gate First live settlement reconciled
    • Outcome Production integration in service
Governance note. Stages 01–03 may run while KYC is pending. Stage 05 is blocked until stage 04 is approved. A rejection returns the merchant to stage 01 with sandbox access withdrawn.

Settlement model

Push tells you something happened. Pull tells you what is true. Implement both before go-live.

Product You start Platform notifies You confirm
LipaPay Collection or checkout Settlement callback Status pull by reference
Lipa Collection MNO, bank, or hosted checkout Settlement callback Status pull by reference
LipaAirtime Voucher or wallet recharge Recharge confirmation Wallet / profile pull
LipaDisbursement Payout instruction No async webhook Payment history pull

Initiate

Create the payment or payout. Persist every reference the platform returns before the customer leaves the flow.

Notify

Accept the callback quickly, make the handler idempotent, and never fulfill solely from the browser redirect.

Confirm

Match amount, status, and reference on your server. Only then mark the order paid or the voucher issued.

Sandbox & live

Sandbox

Test without live funds

Isolated merchant tenant. Simulated settlement. Testing Lab and webhook inspector run here. Safe to break things.

Live

Production integration

Unlocked after KYC approval. Real money movement. Use the same JSON shapes you proved in sandbox — only the host and liability change.

Operating practices

  • Treat notifications as the primary signal and status pulls as recovery — both are required.
  • Make callback handlers idempotent. The same reference may arrive more than once.
  • Store merchant reference, platform control number, and engine payment reference in separate fields.
  • Respond quickly to callbacks; do heavy fulfillment work asynchronously in your system.
  • Verify amount and external reference on the server, not only in the customer browser.
  • Do not share sandbox tokens with production, or live tokens with the Testing Lab.

Support & next step

Integration, settlement, and go-live desks sit on the same platform team.

Ready to build?

Register the merchant to open sandbox. Signed-in teams get the Testing Lab and, after approval, the live switch.

Create merchant account Sign in Support desk