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

LipaAirtime API reference

Sandbox-only API at /api/sandbox/airtime. Same JSON and flow as Lipa_Airtime production — simulated wallet and settlement.

Base: /api/sandbox/airtime Session auth flow Wallet + recharge lifecycle Callback-driven reconciliation Source-mapped contract
POST /api/sandbox/airtime/register

Register

Auth: None

Create sandbox airtime merchant account.

POST /api/sandbox/airtime/login

Login

Auth: None

Authenticate and return bearer token.

POST /api/sandbox/airtime/customer/payments

Airtime Payment

Auth: Bearer token

Send airtime from wallet balance.

POST /api/sandbox/airtime/customer/balancerecharge

Balance Recharge

Auth: Bearer token

Initiate wallet top-up and receive controlNumber.

POST /api/sandbox/airtime/callbackUrl

Recharge Callback

Auth: None

Confirm recharge by controlNumber.

GET /api/sandbox/airtime/user

Current User

Auth: Bearer token

Return authenticated airtime user.

HTTP endpoint surface (source contract)

Method Path Auth Purpose
POST/api/callbackUrlExternal callbackMatch control number, update recharge transaction, increment wallet on success.
GET/api/userSanctumReturn authenticated user context.
POST/customer/paymentsSession authRun airtime purchase from wallet.
POST/customer/bulkpaymentSession authImport bulk airtime requests using Excel flow.
POST/customer/balancerechargeSession authInitiate external top-up to recharge wallet.

Authentication and authorization contract

Item Contract
Primary guardweb session guard with auth and custom is_auth middleware.
Role modelrole_id values: 1 admin, 2 user, 3 finance.
User status modelpending, active, inactive; role 2 requires active status to proceed.
API auth note/api/user relies on Sanctum middleware in source.

Core data contracts

users

Stores identity, role, and status used for role-based redirects and activation checks.

wallet

Per-user wallet with balance used for airtime debit and recharge increments.

payments

Airtime transaction records with provider/network, status, and processing message.

transactions

Wallet recharge records keyed by control number and callback-driven status transitions.

Airtime purchase flow

  1. Validate request payload (msisdn, positive amount).
  2. Load authenticated user wallet by user id.
  3. Reject when requested amount exceeds wallet balance.
  4. Create pending payment record with detected network/provider metadata.
  5. Call external airtime vendor API and evaluate response.
  6. On success, deduct wallet and mark success; on failure, mark failed with message.
  7. Send SMS confirmation or failure notification.

Wallet recharge flow and callback

  1. Authenticate against portal auth API for recharge initiation.
  2. Create pending recharge transaction in local database.
  3. Initiate upstream MNO payment request and capture control number.
  4. Receive callback on /api/callbackUrl with control number and status.
  5. When callback status is true, mark success and increment wallet balance.

Callback minimum payload

{
  "controlNumber": "ABC123",
  "status": true
}

Integrations and reliability notes

  • External integrations include airtime vendor API, portal auth/initiate APIs, and SMS gateways (internal/external).
  • Main orchestration path is implemented through Airtime service and phone/provider helper utilities.
  • Hardening recommendation: move static upstream credentials/tokens to env config, rotate secrets, and add callback signature/IP verification.

Observed source gaps

Route protection

/admin/registerUser appears public in source and should be protected.

Callback validation

Validation focuses on controlNumber while downstream logic also depends on status.

Status consistency

Airtime service status values may diverge from migration/comment expectations.

Source contract mapping

System Method Path
Lipa_Airtime POST /customer/payments
Lipa_Airtime POST /customer/balancerecharge
Lipa_Airtime POST /api/callbackUrl 
{
    "msisdn": "255712345678",
    "amount": 1500
}
{
    "status": "OK",
    "message": "Voucher sent successfully"
}