Wallet and Settlement
Wallet Transactions

Wallet Transactions

Retrieve a paginated list of all transactions for a specific wallet currency. View settlements, payouts, transfers, and other wallet activities with complete transaction history.

Endpoint

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

Sample Request

Endpoint: GET https://api.budpay.com/api/v2/wallet_transactions/NGN

1curl -X GET 'https://api.budpay.com/api/v2/wallet_transactions/NGN' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'
{  "status": true,  "message": "Transfers retrieved",  "data": {    "current_page": 1,    "data": [      {        "id": 44978,        "wallet_id": 58,        "type": "settlement",        "debit": "no",        "currency": "NGN",        "domain": "live",        "amount": "2200",        "note": "Daily settlement on 2023-01-20 with settlement batchID 51f0278755b91",        "bal_before": "15133.40555",        "bal_after": "17333.40555",        "status": "success",        "reference": "51f0278755b91",        "created_at": "2023-01-20T01:42:31.000000Z"      },      {        "id": 30295,        "wallet_id": 58,        "type": "payout",        "debit": "yes",        "currency": "NGN",        "domain": "live",        "amount": "1050",        "note": "Payout with BUD_trf_97e5b6140v4768",        "bal_before": "1203.30555",        "bal_after": "153.30555",        "status": "success",        "reference": "BUD_trf_97e5b6140v4768",        "created_at": "2023-01-11T08:44:31.000000Z"      },      {        "id": 30287,        "wallet_id": 58,        "type": "transfer",        "debit": "yes",        "currency": "NGN",        "domain": "live",        "amount": "19.9",        "note": "Transfer with BUD_trf_m341405537l0k7",        "bal_before": "1223.20555",        "bal_after": "1203.30555",        "status": "success",        "reference": "BUD_trf_m341405537l0k7",        "created_at": "2023-01-11T08:21:41.000000Z"      }    ],    "first_page_url": "https://api.budpay.com/api/v2/wallet_transactions/NGN?page=1",    "from": 1,    "last_page": 23,    "last_page_url": "https://api.budpay.com/api/v2/wallet_transactions/NGN?page=23",    "next_page_url": "https://api.budpay.com/api/v2/wallet_transactions/NGN?page=2",    "path": "https://api.budpay.com/api/v2/wallet_transactions/NGN",    "per_page": 20,    "prev_page_url": null,    "to": 20,    "total": 449  }}
Powered byXendr

Request Parameters

Path Parameters

ParameterTypeRequiredDescription
currencyStringYesCurrency code: NGN, KES, GHS, or USD

Query Parameters

ParameterTypeRequiredDescription
pageIntegerNoPage number (default: 1)

Header Parameters

Field NameDescriptionRequired
AuthorizationBearer token with your secret keyYes

Response Fields

Pagination Fields

FieldTypeDescription
statusBooleanIndicates if request was successful
messageStringResponse message
data.current_pageIntegerCurrent page number
data.per_pageIntegerNumber of items per page
data.totalIntegerTotal number of transactions
data.last_pageIntegerLast page number
data.fromIntegerStarting transaction number on current page
data.toIntegerEnding transaction number on current page
data.first_page_urlStringURL for first page
data.last_page_urlStringURL for last page
data.next_page_urlStringURL for next page (null if last page)
data.prev_page_urlStringURL for previous page (null if first page)

Transaction Object Fields

FieldTypeDescription
idIntegerInternal transaction ID
wallet_idIntegerWallet ID
typeStringTransaction type: settlement, payout, transfer
debitStringDebit indicator: yes or no
currencyStringTransaction currency
domainStringEnvironment: test or live
amountStringTransaction amount
noteStringTransaction description/note
bal_beforeStringWallet balance before transaction
bal_afterStringWallet balance after transaction
statusStringTransaction status
referenceStringUnique transaction reference
created_atStringTransaction timestamp

Transaction Types

TypeDescriptionDebit/Credit
settlementDaily settlement from successful paymentsCredit (debit: no)
payoutBank transfer payout initiatedDebit (debit: yes)
transferFund transferDebit (debit: yes)
refundPayment refund processedDebit (debit: yes)
chargeFee or charge appliedDebit (debit: yes)

Pagination Example

Navigate Through Pages

Endpoint: GET https://api.budpay.com/api/v2/wallet_transactions/NGN

1curl -X GET 'https://api.budpay.com/api/v2/wallet_transactions/NGN' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'
Powered byXendr

Endpoint: GET https://api.budpay.com/api/v2/wallet_transactions/NGN?page=2

1curl -X GET 'https://api.budpay.com/api/v2/wallet_transactions/NGN?page=2' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'
Powered byXendr

Endpoint: GET https://api.budpay.com/api/v2/wallet_transactions/NGN?page=5

1curl -X GET 'https://api.budpay.com/api/v2/wallet_transactions/NGN?page=5' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'
Powered byXendr

Error Handling

401 Unauthorized

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

404 Not Found

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

422 Validation Error

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

Best Practices

Tip: Use this endpoint for reconciliation, accounting, and generating detailed financial reports for your wallet activities.

  1. Pagination: Process transactions page by page for large datasets
  2. Reconciliation: Regular checks to match internal records with wallet transactions
  3. Filtering: Use transaction type and reference for targeted queries
  4. Balance Tracking: Monitor bal_before and bal_after for accuracy verification
  5. Date Ranges: Implement date filtering on your end for specific periods
  6. Export Data: Retrieve and store transaction history for accounting purposes
  7. Status Monitoring: Track transaction status for failed or pending items

Reconciliation Workflow

💡

Accounting: Use wallet transactions for daily reconciliation and financial audits. Compare bal_after values to ensure data integrity.

  1. Fetch Transactions: Retrieve all transactions for the period
  2. Verify Balances: Check bal_before and bal_after calculations
  3. Match References: Cross-reference with your internal transaction records
  4. Identify Discrepancies: Flag any mismatches for investigation
  5. Generate Reports: Create financial reports from transaction data

Transaction Analysis

Calculate Net Change

Net Change = bal_after - bal_before

Example:
Settlement: 17333.40555 - 15133.40555 = +2200 (Credit)
Payout: 153.30555 - 1203.30555 = -1050 (Debit)

Filter by Type

  • Credits (Settlements): debit: "no" - Incoming funds
  • Debits (Payouts/Transfers): debit: "yes" - Outgoing funds

Security Considerations

⚠️

Security: Wallet transaction data contains sensitive financial information. Always handle securely and restrict access appropriately.

  • Server-Side Only: Query wallet transactions from your secure backend
  • HTTPS Only: Use secure connections for all requests
  • Access Control: Restrict access to authorized personnel only
  • Data Privacy: Handle financial data according to compliance requirements
  • Audit Logs: Maintain logs of who accesses wallet transaction data

Next Steps

Wallet BalanceSettlements