12-Jun-2026
Home / Documentation / API reference
EN sandbox@lipapay.test Sign in LP

Unified Sandbox API

Conceptual Flow

This section explains how the platform works at a high level, without requiring technical endpoint knowledge.

Public-safe guidance System-flow aligned Product-by-product context Auth-first operations

LipaPay Core

Used for standard payment collection between customer and merchant, including secure checkout patterns.

LipaAirtime

Used for airtime and top-up journeys, built on collection logic with airtime-specific business behavior.

LipaDisbursement

Used for outbound payout/disbursement journeys where a merchant transfers value to a recipient.

Normal User Journey

  1. User creates an account, then accesses services only after account activation and successful login.
  2. Authenticated users can initiate transaction workflows according to their permitted product scope.
  3. The platform validates details and creates a transaction reference for each request.
  4. Transactions pass through processing states such as pending, success, or failed.
  5. Merchants reconcile using status checks and event updates from callback handling.

Access and Authentication Flow

How developers gain access

Use your registered account credentials to sign in, then proceed with product integrations based on your approved merchant profile.

Step What happens Result
Account registrationDeveloper creates sandbox account through portal onboarding.Account enters normal activation flow.
Account loginDeveloper signs in with approved account credentials.Authenticated access to protected product workspaces.
Flow authorizationSystem applies product permissions and role checks.Only allowed actions become available in the dashboard.

LipaPay Core Developer Flow

Aligned with the `LipaPay_Ver2` project, this flow covers primary collections and checkout behavior.

1. Initiate collection

Submit transaction request with payer and amount details using your authenticated context.

2. Track processing state

Use your transaction reference to monitor pending, success, and failure states.

3. Reconcile and confirm

Finalize order state only after verification from status or callback events.

LipaAirtime Developer Flow

Aligned with the `Lipa_Airtime` project, airtime integration extends collection behavior with airtime-specific validation and fulfillment lifecycle.

1. Validate subscriber details

Capture network/subscriber inputs and validate according to your business rules.

2. Submit airtime request

Create airtime transaction from authenticated user context and capture control reference.

3. Confirm fulfillment outcome

Reconcile fulfillment by checking final state and handling callback events safely.

LipaDisbursement Developer Flow

Aligned with the `LipaDisbursement` project, this flow is for controlled outbound payout/disbursement operations.

1. Prepare beneficiary data

Validate recipient identity and payout amount before request submission.

2. Execute disbursement request

Send payout request and store generated payout reference for audit and tracing.

3. Handle reconciliation

Complete ledger updates using final status and callback signals in your merchant system.

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.

1

Initiate

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

2

Pending

Customer completes USSD/bank/checkout or voucher flow.

3

Push (callback)

Platform or engine notifies your endpoint with settlement payload.

4

Pull (status)

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

5

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 pay_mobile, initiate-payment/mno|bank, or initiate-secure-payment POST /api/sandbox/transaction/status

After login — on-demand reconciliation when a callback is delayed or missing.

 GET or POST /api/sandbox/callback

Simulates LipaPay engine settlement; updates in-memory txn then visible via status.

 reference (engine)
controlNumber (portal MNO/bank)
external_reference (secure)
LipaAirtime POST /api/sandbox/airtime/customer/payments or balancerecharge GET /api/sandbox/airtime/user

Wallet balance and profile pull — use callbackUrl to confirm recharge by controlNumber.

 POST /api/sandbox/airtime/callbackUrl

Matches production Lipa_Airtime callbackUrl — marks pending recharge successful.

 controlNumber
LipaDisbursement POST /api/sandbox/disbursement/payment POST /api/sandbox/disbursement/getPayments

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)

Sandbox contracts (copy-ready)

LipaPay status POST /api/sandbox/transaction/status 
{
  "ref_id": "CONTROL_OR_ENGINE_REF"
}

Authorization: Bearer <Sanctum token>

LipaPay engine callback /api/sandbox/callback 
{
  "message": "success",
  "code": "200",
  "status": true,
  "description": "Payment received",
  "data": {
    "providerType": "MNO",
    "providerName": "Vodacom",
    "amount": 1000,
    "paymentReference": "YOUR_ENGINE_REFERENCE",
    "payerMobile": "255712345678",
    "transactionDate": "2026-05-29 12:00:00",
    "transactionID": "TXN-ABC123",
    "transactionChannel": "USSD"
  }
}
LipaAirtime callbackUrl POST /api/sandbox/airtime/callbackUrl 
{
  "controlNumber": "FROM_RECHARGE_RESPONSE",
  "status": true
}
LipaDisbursement history POST /api/sandbox/disbursement/getPayments 
{
  "payments": {
    "data": [
      { "txnid": "…", "refid": "…", "amount": 1000 }
    ]
  }
}

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 open testing lab Interactive callback tester