Wallet Balance

Retrieve the available balance in your BudPay wallet for a specific currency. Use this endpoint to check available funds before initiating transfers or payouts.

Endpoint

GET https://api.budpay.com/api/v2/wallet_balance/{currency}

Sample Request

curl https://api.budpay.com/api/v2/wallet_balance/NGN \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET

Sample Response

{
    "success": true,
    "message": "Wallet Balance Fetched Successfully",
    "data": {
        "currency": "NGN",
        "balance": "2793.40555"
    }
}

Try it out

Request Parameters

Path Parameters

Parameter	Type	Required	Description
`currency`	String	Yes	Currency code: `NGN`, `KES`, `GHS`, or `USD`

Header Parameters

Field Name	Description	Required
Authorization	Bearer token with your secret key	Yes

Response Fields

Field	Type	Description
`success`	Boolean	Indicates if request was successful
`message`	String	Response message
`data.currency`	String	Currency code of the wallet
`data.balance`	String	Available balance in the specified currency

Supported Currencies

Currency	Country	Description
NGN	Nigeria	Nigerian Naira
KES	Kenya	Kenyan Shilling
GHS	Ghana	Ghanaian Cedi
USD	International	US Dollar

Error Handling

401 Unauthorized

{
    "success": false,
    "message": "Authentication failed"
}

404 Not Found

{
    "success": false,
    "message": "Wallet not found for specified currency"
}

422 Validation Error

{
    "success": false,
    "message": "Invalid currency code"
}

Best Practices

Tip: Check wallet balance before initiating transfers to ensure sufficient funds and prevent failed transactions.

Pre-Transfer Verification: Always check balance before initiating payouts
Include Fees: Factor in transaction fees when checking available balance
Multi-Currency Management: Check balances for each currency separately
Balance Alerts: Implement low balance alerts for automated systems
Real-Time Checks: Query balance immediately before large transfers
Cache Carefully: Balance data should not be cached for extended periods
Error Handling: Handle insufficient balance errors gracefully in your application

Balance Management Tips

💡

Planning: For bulk transfers, verify that balance ≥ (total_amount + total_fees) before processing.

Single Transfer Validation

Required Balance = Transfer Amount + Transaction Fee
Example: NGN 100 + NGN 10 = NGN 110

Bulk Transfer Validation

Required Balance = Sum of All Amounts + Sum of All Fees
Example: (NGN 100 × 3) + (NGN 10 × 3) = NGN 330

Integration Examples

Balance Check Before Transfer

// Check balance
const balanceResponse = await getWalletBalance('NGN');
const availableBalance = parseFloat(balanceResponse.data.balance);
 
// Calculate required amount
const transferAmount = 100;
const transferFee = 10;
const requiredBalance = transferAmount + transferFee;
 
// Verify sufficient funds
if (availableBalance >= requiredBalance) {
    // Proceed with transfer
    await initiateBankTransfer(transferData);
} else {
    // Handle insufficient balance
    throw new Error('Insufficient wallet balance');
}

Security Considerations

⚠️

Security: Never expose wallet balance information in client-side code or logs accessible to end users.

Server-Side Only: Always check balance from your secure backend
HTTPS Only: Use secure connections for all balance queries
Access Control: Restrict balance queries to authorized personnel/systems
Data Privacy: Handle balance information according to your security policies

Next Steps

Single Payout - Initiate individual bank transfers
Bulk Payout - Process multiple transfers in batch
Payout Fees - Calculate transfer fees
Verify Transfer - Check transfer status

Overview Wallet Transactions