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.
/wallet/partner/walletGet balance
{
"success": true,
"data": {
"wallet": {
"id": "b2b2c6c0-...",
"balance": "1250.00",
"currency": "NGN",
"low_balance_threshold": null
}
}
}/wallet/ledger/partner/wallet/ledgerList ledger entries
Query params: limit (default 50, max 200), offset.
{
"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.
/wallet/fund/initialize/partner/wallet/fund/initializeStart a funding attempt
{
"amount": "5000.00",
"callback_url": "https://yourapp.com/wallet/callback",
"gateway": "paystack"
}{
"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.
/wallet/fund/verify/{reference}/partner/wallet/fund/verify/{reference}Check a funding attempt
{
"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.
/partner/wallet/auto-reloadGet auto-reload settings
{
"success": true,
"data": {
"enabled": true,
"amount": "20000.00",
"low_balance_threshold": "5000.00",
"has_saved_payment_method": true
}
}/partner/wallet/auto-reloadSet auto-reload settings
{
"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.