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

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

Sample Response

{
    "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
    }
}

Try it out

Request Parameters

Path Parameters

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

Query Parameters

Parameter	Type	Required	Description
`page`	Integer	No	Page number (default: 1)

Header Parameters

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

Response Fields

Pagination Fields

Field	Type	Description
`status`	Boolean	Indicates if request was successful
`message`	String	Response message
`data.current_page`	Integer	Current page number
`data.per_page`	Integer	Number of items per page
`data.total`	Integer	Total number of transactions
`data.last_page`	Integer	Last page number
`data.from`	Integer	Starting transaction number on current page
`data.to`	Integer	Ending transaction number on current page
`data.first_page_url`	String	URL for first page
`data.last_page_url`	String	URL for last page
`data.next_page_url`	String	URL for next page (null if last page)
`data.prev_page_url`	String	URL for previous page (null if first page)

Transaction Object Fields

Field	Type	Description
`id`	Integer	Internal transaction ID
`wallet_id`	Integer	Wallet ID
`type`	String	Transaction type: `settlement`, `payout`, `transfer`
`debit`	String	Debit indicator: `yes` or `no`
`currency`	String	Transaction currency
`domain`	String	Environment: `test` or `live`
`amount`	String	Transaction amount
`note`	String	Transaction description/note
`bal_before`	String	Wallet balance before transaction
`bal_after`	String	Wallet balance after transaction
`status`	String	Transaction status
`reference`	String	Unique transaction reference
`created_at`	String	Transaction timestamp

Transaction Types

Type	Description	Debit/Credit
`settlement`	Daily settlement from successful payments	Credit (debit: no)
`payout`	Bank transfer payout initiated	Debit (debit: yes)
`transfer`	Fund transfer	Debit (debit: yes)
`refund`	Payment refund processed	Debit (debit: yes)
`charge`	Fee or charge applied	Debit (debit: yes)

Pagination Example

Navigate Through Pages

# Get page 1 (default)
curl https://api.budpay.com/api/v2/wallet_transactions/NGN
 
# Get page 2
curl https://api.budpay.com/api/v2/wallet_transactions/NGN?page=2
 
# Get page 5
curl https://api.budpay.com/api/v2/wallet_transactions/NGN?page=5

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.

Pagination: Process transactions page by page for large datasets
Reconciliation: Regular checks to match internal records with wallet transactions
Filtering: Use transaction type and reference for targeted queries
Balance Tracking: Monitor bal_before and bal_after for accuracy verification
Date Ranges: Implement date filtering on your end for specific periods
Export Data: Retrieve and store transaction history for accounting purposes
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.

Fetch Transactions: Retrieve all transactions for the period
Verify Balances: Check bal_before and bal_after calculations
Match References: Cross-reference with your internal transaction records
Identify Discrepancies: Flag any mismatches for investigation
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 Balance - Check current wallet balance
Single Payout - Initiate bank transfers
Bulk Payout - Process multiple transfers
Verify Transfer - Check specific transfer status

Wallet Balance Settlements