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

LipaDisbursement API reference

Sandbox-only API at /api/sandbox/disbursement. Same JSON and flow as LipaDisbursement production — simulated wallet debits and payouts.

Base: /api/sandbox/disbursement Bearer auth Wallet + charge controls Provider dispatch + SMS notify Audit-ready reconciliation
POST /api/sandbox/disbursement/register

Register

Auth: None

Create sandbox disbursement account.

POST /api/sandbox/disbursement/login

Login

Auth: None

Authenticate and return user, wallet, and token.

POST /api/sandbox/disbursement/logout

Logout

Auth: Bearer token

Revoke current access token.

POST /api/sandbox/disbursement/payment

Payment

Auth: Bearer token

Create disbursement and deduct wallet.

POST /api/sandbox/disbursement/getPayments

Get Payments

Auth: Bearer token

List authenticated user payments.

GET /api/sandbox/disbursement/user

Current User

Auth: Bearer token

Return authenticated user profile.

Public API surface (source contract)

Method Path Auth Behavior
POST/api/registerNoneRegister user and issue access token.
POST/api/loginNoneAuthenticate user and return user, wallet, and token.
POST/api/logoutBearer tokenRevoke current access token.
POST/api/paymentBearer tokenCreate disbursement request and apply wallet deduction on success.
POST/api/getPaymentsBearer tokenList authenticated user disbursement records (latest first).
GET/api/userBearer tokenReturn authenticated user profile payload.

Authentication contract

Item Contract
API guardauth:api (Passport token model).
Protected endpoints/api/logout, /api/payment, /api/getPayments, /api/user.
Login restrictionsUsers with status unverified or rejected are blocked.
Password handlingPasswords are stored as hashed values before persistence.

Payment payload rules

Field Type Required Rule summary
msisdnstringYesTanzanian format 255XXXXXXXXX; provider must be resolvable.
amountnumberYesUsed for charge calculation and wallet sufficiency check.
namestringYesRecipient/customer label saved on payment record.

Disbursement processing sequence

  1. Validate payload fields and reject malformed input.
  2. Run MSISDN format and provider checks.
  3. Calculate charge and verify wallet balance covers amount + charge.
  4. Create pending payment record with generated reference id.
  5. Send upstream disbursement request to provider gateway.
  6. On success, run wallet deduction and mark payment completed in transaction-safe flow.
  7. Trigger recipient SMS notification with reference and amount details.
  8. Return success payload to client with upstream response metadata.

Error behavior (source observed)

400

Invalid MSISDN, unsupported provider, or disbursement initiation failure.

401

Unauthorized token or blocked login status (unverified/rejected).

422

Validation failure or insufficient wallet balance.

Source contract mapping

System Method Path
LipaDisbursement POST /api/register
LipaDisbursement POST /api/login
LipaDisbursement POST /api/payment
LipaDisbursement POST /api/getPayments

Developer source: LipaDisbursement project

This disbursement reference is intentionally mapped to the LipaDisbursement developer API contract: POST /api/login, POST /api/payment, POST /api/getPayments.

Sandbox equivalents are exposed under /api/sandbox so frontend flow stays consistent while local testing remains isolated.

Data contracts and integration notes

  • Core tables participating in payout flow: users, wallets, payments, balance_transactions, tigo_wallet.
  • Primary external channels: disbursement provider gateway and SMS gateway.
  • Operational hardening recommendation: move keys/endpoints fully into environment configuration and rotate sensitive values.
{
    "msisdn": "255712345678",
    "amount": 10000,
    "name": "Recipient Name"
}
{
    "message": "Payment created successfully",
    "response": {
        "status": true,
        "reference": "123456789",
        "message": "Disbursement accepted"
    }
}