You're offline — reconnect to continue buying or checking your wallet.
Core concepts

Wallet & funding

Every purchase debits a wallet. A partner's test and live keys each hold their own wallet, funding one never affects the other. Balances are never edited directly; every change is a row in an immutable ledger, which is exactly what these endpoints read from.

GET/wallet
GET/partner/wallet

Get balance

200 response
{
  "success": true,
  "data": {
    "wallet": {
      "id": "b2b2c6c0-...",
      "balance": "1250.00",
      "currency": "NGN",
      "low_balance_threshold": null
    }
  }
}
GET/wallet/ledger
GET/partner/wallet/ledger

List ledger entries

Query params: limit (default 50, max 200), offset.

200 response
{
  "success": true,
  "data": {
    "entries": [
      {
        "id": "1a2b3c...",
        "type": "debit",
        "amount": "200.00",
        "balance_before": "1450.00",
        "balance_after": "1250.00",
        "description": "airtime purchase",
        "reference": "purchase-PO-17C0EA5155C544FF",
        "payment_reference": null,
        "created_at": "2026-11-17T16:11:00Z"
      }
    ],
    "limit": 50,
    "offset": 0
  }
}

type is one of credit, debit, refund, or adjustment.

POST/wallet/fund/initialize
POST/partner/wallet/fund/initialize

Start a funding attempt

Request body
{
  "amount": "5000.00",
  "callback_url": "https://yourapp.com/wallet/callback",
  "gateway": "paystack"
}
201 response
{
  "success": true,
  "data": {
    "reference": "TR-9F1C2A3B4D5E6F70",
    "authorization_url": "https://checkout.paystack.com/...",
    "amount": "5000.00"
  }
}

Redirect to authorization_url to complete payment. The gateway's webhook is what actually credits the wallet; verify below is a fallback for confirming the result from your own redirect handler, not the primary signal.

GET/wallet/fund/verify/{reference}
GET/partner/wallet/fund/verify/{reference}

Check a funding attempt

200 response
{
  "success": true,
  "data": {
    "funding": {
      "id": "c4d5e6f7-...",
      "reference": "TR-9F1C2A3B4D5E6F70",
      "gateway": "paystack",
      "amount": "5000.00",
      "currency": "NGN",
      "status": "success",
      "authorization_url": "https://checkout.paystack.com/...",
      "created_at": "2026-11-17T16:09:00Z",
      "completed_at": "2026-11-17T16:09:42Z"
    }
  }
}

Safe to call repeatedly, once a funding attempt reaches success, calling verify again returns the same result without crediting the wallet a second time.

Auto-reload

Partner-only. A wallet that quietly hits zero fails every purchase for your own end-customers with no warning, this is the fix. Fund the wallet once through the normal flow above, that funding captures a reusable charge token automatically, then turn auto-reload on: once your balance drops below the threshold you set, it's topped back up on its own, no redirect, no manual step. Until you've funded at least once, there's nothing to charge yet, so only the low-balance email alert fires.

GET/partner/wallet/auto-reload

Get auto-reload settings

200 response
{
  "success": true,
  "data": {
    "enabled": true,
    "amount": "20000.00",
    "low_balance_threshold": "5000.00",
    "has_saved_payment_method": true
  }
}
PUT/partner/wallet/auto-reload

Set auto-reload settings

Request body
{
  "enabled": true,
  "amount": "20000.00",
  "low_balance_threshold": "5000.00"
}

amount is how much each reload adds. low_balance_threshold is shared with the low-balance alert, the same field also comes back on GET /wallet as low_balance_threshold. Set enabled: false to keep the threshold (for the email alert) without auto-charging.