Wallet & Settlement Management

Manage your BudPay wallet balances, view transaction history, and track settlement batches across multiple currencies. The wallet system tracks all financial activities including settlements, payouts, transfers, and fees.

Overview

The BudPay wallet is your central account for managing funds across different currencies. It automatically receives settlements from successful payments and allows you to initiate payouts to bank accounts. Every successful payment transaction is processed through daily settlement batches that credit funds to your wallet.

Key Features

Wallet Transaction Types

Understanding Settlements

What is a Settlement?

A settlement is a batch of successful payment transactions that have been processed and the funds transferred to your wallet. Each settlement includes:

• Batch ID: Unique identifier for the settlement batch
• Total Amount: Sum of all transaction amounts in the batch
• Fees: Transaction processing fees deducted
• Settled Amount: Net amount credited to your wallet (Total - Fees)
• Transactions: List of individual transactions in the batch

Settlement Calculation:

Settled Amount = Total Amount - Transaction Fees

Example:
Total Amount: NGN 1,000
Transaction Fees: NGN 14
Settled Amount: NGN 986

Settlement Frequency:

• Daily Settlements: Processed once per day for previous day's transactions
• Automatic: No action required from you
• Notifications: Webhook notifications sent for each settlement batch
• Multi-Currency: Separate settlements for each currency

Supported Currencies

Wallet & Settlement Workflow

1. Receive Payments

• Customer completes payment transaction
• Transaction processed successfully
• Funds held for settlement processing

2. Daily Settlement

• Transactions grouped into daily settlement batch
• Transaction fees calculated and deducted
• Net amount credited to wallet
• Settlement batch created with unique batch ID

3. Check Balance & Settlements

• Query current wallet balance for specific currency
• View settlement history and batch details
• Monitor transaction-level details within batches
• Verify sufficient funds before transfers

4. View Transaction History

• Access complete wallet transaction history
• Filter by type, date, or reference
• Reconcile settlements with wallet transactions
• Generate financial reports

5. Initiate Payouts

• Transfer funds from wallet to bank accounts
• Process single or bulk payouts
• Track payout status via reference ID

Available Endpoints

Balance Management

Balance Verification Formula

Required Balance = Transfer Amount + Transaction Fee

Example:
Transfer: NGN 1,000
Fee: NGN 10
Required: NGN 1,010

Bulk Transfer Calculation

Required Balance = Sum(All Amounts) + Sum(All Fees)

Example (3 transfers):
Amounts: NGN 1,000 + 500 + 750 = 2,250
Fees: NGN 10 + 10 + 10 = 30
Required: NGN 2,280

Transaction Tracking

Every wallet transaction includes:

• Reference ID: Unique identifier for tracking
• Transaction Type: Settlement, payout, transfer, etc.
• Amount: Transaction value
• Balance Before: Wallet balance before transaction
• Balance After: Wallet balance after transaction
• Status: Success, pending, or failed
• Timestamp: Transaction creation date/time

Settlement Reconciliation

Daily Reconciliation Steps:

1. Fetch Settlements: Retrieve all settlement batches for the period
2. Get Settlement Details: View individual transactions within each batch
3. Match Wallet Transactions: Find corresponding wallet transactions by batch ID
4. Verify Amounts: Confirm settled amounts match wallet credits
5. Calculate Fees: Sum transaction fees for cost analysis
6. Generate Reports: Create financial reports from settlement data

Settlement to Wallet Matching:

Settlement Batch ID: 3748219937352
Total Amount: NGN 101.4
Fees: NGN 1.4
Settled Amount: NGN 100
                ↓
Wallet Transaction Reference: 3748219937352
Type: Settlement
Amount: NGN 100
Status: Success ✓

Balance Verification:

Opening Balance + Settlements - Payouts - Fees = Closing Balance

Example:
Opening: NGN 10,000
Settlements: NGN 5,000
Payouts: NGN 3,000
Fees: NGN 500
Closing: NGN 11,500 ✓

Best Practices

1. Regular Balance Checks: Monitor wallet balance regularly, especially before bulk operations
2. Settlement Monitoring: Review daily settlements for accurate revenue tracking
3. Low Balance Alerts: Set up notifications when balance falls below threshold
4. Transaction Logging: Store transaction and settlement references for audit trails
5. Daily Reconciliation: Match settlements and wallet transactions with internal records
6. Multi-Currency Tracking: Monitor each currency wallet and settlement separately
7. Fee Analysis: Track settlement fees for cost monitoring and optimization
8. Webhook Integration: Use webhooks for real-time settlement and transaction notifications

Common Operations

Check Balance Before Transfer

// Get wallet balance
const balance = await getWalletBalance('NGN');
 
// Calculate required amount
const amount = 1000;
const fee = await getPayoutFee('NGN', amount);
const required = amount + fee;
 
// Verify sufficient funds
if (balance >= required) {
    await initiateTransfer(data);
}

View Recent Settlements

// Get settlement history
const settlements = await getSettlements();
 
// Calculate total revenue
const totalRevenue = settlements.data.reduce((sum, s) => {
    return sum + parseFloat(s.total_amount);
}, 0);
 
// Calculate total fees
const totalFees = settlements.data.reduce((sum, s) => {
    const fee = parseFloat(s.total_amount) - parseFloat(s.settled_amount);
    return sum + fee;
}, 0);

Get Settlement Details

// Get specific settlement with transactions
const batchid = '3748219937352';
const settlement = await getSettlementDetails(batchid);
 
// View transactions in batch
const transactions = settlement.transactions;
console.log(`Batch contains ${transactions.length} transactions`);

View Recent Transactions

// Get latest transactions
const transactions = await getWalletTransactions('NGN', page=1);
 
// Filter settlements
const settlements = transactions.data.filter(t => t.type === 'settlement');
 
// Calculate total credits
const totalCredits = settlements.reduce((sum, t) => sum + parseFloat(t.amount), 0);

Security Considerations

• Server-Side Only: Never expose wallet or settlement endpoints to client-side code
• HTTPS Only: Always use secure connections for all financial operations
• Access Control: Restrict access to authorized personnel only
• Audit Logging: Maintain detailed logs of all queries and operations
• Data Protection: Handle financial data according to regulatory requirements
• Key Management: Secure API keys with environment variables and secrets management

Integration Workflow

Complete Financial Management Flow:

1. Monitor Settlements: Track daily settlement batches and amounts
2. Check Balance: Verify sufficient funds in currency wallet
3. Review Transactions: Analyze wallet transaction history
4. Reconcile Data: Match settlements with wallet transactions
5. Calculate Fees: Get accurate transaction fees for payouts
6. Validate Accounts: Verify recipient bank account details
7. Initiate Transfers: Create single or bulk payout requests
8. Track Status: Monitor transfer status via reference ID or webhook
9. Update Records: Record all activities in your system
10. Daily Reconciliation: Match all financial data with internal records

Next Steps

Get Started:

• Wallet Balance - Check your available balance
• Wallet Transactions - View transaction history
• Settlement History - View settlement batches
• Settlement Details - Get detailed settlement info

Related Features:

• Single Payout - Initiate individual transfers
• Bulk Payout - Process batch payouts
• Payout Fees - Calculate transfer fees
• Verify Transfer - Check payout status