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

Getting Started

Introduction

Unified Sandbox API Documentation

This sandbox gives one developer workspace for all three offerings: LipaPay (core collections), LipaAirtime (airtime service), and LipaDisbursement (payout service). Build and test each product flow before production onboarding.

Flow-first onboarding Role-aware access Product-specific references Status + callback validation

1) Access, Authentication & Go-live

Register in sandbox, sign in, then test all products in the API testing lab (after sign-in) and submit KYC for live portal credentials (after sign-in). After approval, LipaPay emails production portal access — not instant keys here.

After submission, LipaPay compliance reviews your application and contacts you by email with live portal access when approved.

Authentication details

Item Value Purpose
Account onboarding Register and activate account Ensures access follows your merchant activation workflow.
Developer login Sign in with approved credentials Unlocks authenticated product areas, API keys, KYC, and testing tools.

2) LipaPay Core Flow

LipaPay is the core product used for payment collections and secure checkout-related operations. Standard flow is: authenticate, initiate payment, then track transaction status.

Collection Initiation

Create customer collection request under authenticated merchant context.

Alternative Bank Initiation

Use bank-oriented initiation path when checkout channel requires bank flow.

Transaction Status

Reconcile asynchronous processing and confirm final transaction outcome.

3) LipaAirtime Service Flow

LipaAirtime uses the same sandbox auth model and collection-style request contract. Submit airtime request data, capture reference/control number, then perform status verification for reconciliation.

Detailed Airtime documentation: Airtime overview and Airtime API reference.

4) LipaDisbursement Service Flow

Use /api/sandbox/disbursement/* for register, login, payment, and list payments. Responses match the LipaDisbursement production API (data, wallet, token on login).

Payment API

POST payment with msisdn, amount, and name after Bearer login; wallet debited with MNO charge rules.

Status Check

Track pending-to-complete lifecycle and reconciliation states.

Callback Stub

Validate callback payload handling before production webhook onboarding.

Detailed Disbursement documentation: Disbursement overview and Disbursement API reference.

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

API reference — status & callbacks Interactive testers Sign in for testing lab