Settlements – BudPay

Settlement History

Retrieve a list of all settlement batches processed to your wallet. View historical settlement data including amounts, fees, and processing dates.

Endpoint

GET https://api.budpay.com/api/v2/settlement

Sample Request

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

Sample Response

{
    "status": true,
    "message": "settlement retrieved",
    "data": [
        {
            "id": 3391,
            "batchid": "3748219937352",
            "currency": "NGN",
            "total_amount": "101.4",
            "settled_amount": "100",
            "domain": "live",
            "status": "success",
            "subaccount": null,
            "created_at": "2023-01-02T01:40:43.000000Z",
            "updated_at": "2023-01-02T01:40:43.000000Z"
        },
        {
            "id": 3375,
            "batchid": "017315e113ae4",
            "currency": "NGN",
            "total_amount": "1318.2",
            "settled_amount": "1300",
            "domain": "live",
            "status": "success",
            "subaccount": null,
            "created_at": "2022-12-30T01:40:42.000000Z",
            "updated_at": "2022-12-30T01:40:42.000000Z"
        },
        {
            "id": 3362,
            "batchid": "9635111901164",
            "currency": "NGN",
            "total_amount": "202.8",
            "settled_amount": "200",
            "domain": "live",
            "status": "success",
            "subaccount": null,
            "created_at": "2022-12-29T01:40:39.000000Z",
            "updated_at": "2022-12-29T01:40:39.000000Z"
        }
    ],
    "meta": {
        "total": 3
    }
}

Try it out

Request Parameters

Header Parameters

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

Response Fields

Field	Type	Description
`status`	Boolean	Indicates if request was successful
`message`	String	Response message
`data`	Array	Array of settlement batch objects
`meta.total`	Integer	Total number of settlements

Settlement Object Fields

Field	Type	Description
`id`	Integer	Internal settlement ID
`batchid`	String	Unique settlement batch identifier
`currency`	String	Settlement currency (NGN, KES, GHS, USD)
`total_amount`	String	Total transaction amount before fees
`settled_amount`	String	Amount credited to wallet after fees
`domain`	String	Environment: `test` or `live`
`status`	String	Settlement status
`subaccount`	String	Subaccount ID (if applicable)
`created_at`	String	Settlement creation timestamp
`updated_at`	String	Last update timestamp

Settlement Status

Status	Description
`success`	Settlement completed and credited to wallet
`pending`	Settlement being processed
`failed`	Settlement failed (contact support)

Understanding Settlement Amounts

Fee Deduction: The difference between total_amount and settled_amount represents transaction fees and charges.

Settlement Calculation:

Settled Amount = Total Amount - Transaction Fees

Example:
Total Amount: NGN 101.4
Fees: NGN 1.4
Settled Amount: NGN 100

Fee Breakdown:

Transaction fees from successful payments
Processing charges
Currency conversion fees (if applicable)

Error Handling

401 Unauthorized

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

404 Not Found

{
    "status": false,
    "message": "No settlements found"
}

Best Practices

Tip: Use settlement data for financial reconciliation and accounting. Cross-reference batch IDs with wallet transactions for complete audit trails.

Regular Monitoring: Check settlement history regularly for accounting purposes
Reconciliation: Match settlement batch IDs with wallet transactions
Fee Tracking: Monitor fee amounts for cost analysis
Record Keeping: Store settlement data for financial records and audits
Verify Amounts: Cross-check settled amounts with expected revenue
Date Tracking: Track settlement dates for cash flow planning
Currency Separation: Review settlements by currency for multi-currency operations

Get Settlement Details

Retrieve detailed information about a specific settlement batch including all transactions within that batch.

Endpoint

GET https://api.budpay.com/api/v2/settlement/details/{batchid}

Sample Request

curl https://api.budpay.com/api/v2/settlement/details/1166806529561 \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET

Sample Response

{
    "status": true,
    "message": "Settlement retrieved",
    "data": {
        "id": 3508,
        "batchid": "1166806529561",
        "currency": "NGN",
        "total_amount": "70",
        "settled_amount": "20",
        "domain": "live",
        "status": "success",
        "subaccount": null,
        "created_at": "2023-01-15T01:41:31.000000Z",
        "updated_at": "2023-01-15T01:41:31.000000Z"
    },
    "transactions": [
        {
            "id": 1413380,
            "currency": "NGN",
            "amount": "70",
            "fees": "50",
            "requested_amount": "20",
            "reference": "8363870232148760",
            "channel": "transfer",
            "domain": "live",
            "status": "success",
            "customer_id": 482207,
            "created_at": "2023-01-14T21:05:54.000000Z",
            "paid_at": "2023-01-14 22:07:31"
        }
    ]
}

Try it out

Request Parameters

Parameter	Type	Required	Description
`batchid`	String	Yes	Unique settlement batch identifier

Response Fields

Settlement Data:

Field	Type	Description
`data.id`	Integer	Internal settlement ID
`data.batchid`	String	Unique settlement batch identifier
`data.currency`	String	Settlement currency
`data.total_amount`	String	Total transaction amount before fees
`data.settled_amount`	String	Amount credited to wallet after fees
`data.domain`	String	Environment: `test` or `live`
`data.status`	String	Settlement status
`data.created_at`	String	Settlement creation timestamp
`data.updated_at`	String	Last update timestamp

Transaction Fields:

Field	Type	Description
`id`	Integer	Transaction ID
`currency`	String	Transaction currency
`amount`	String	Transaction amount
`fees`	String	Transaction fees charged
`requested_amount`	String	Net amount after fees
`reference`	String	Transaction reference ID
`channel`	String	Payment channel (transfer, card, etc.)
`domain`	String	Environment: `test` or `live`
`status`	String	Transaction status
`customer_id`	Integer	Customer identifier
`created_at`	String	Transaction creation timestamp
`paid_at`	String	Payment completion timestamp

Error Handling

404 Not Found

{
    "status": false,
    "message": "Settlement batch not found"
}

Settlement Schedule

💡

Daily Settlements: BudPay typically processes settlements daily for completed transactions. Check your account settings for specific settlement schedules.

Typical Settlement Flow:

Transaction Complete: Customer payment successfully processed
Batch Collection: Transactions grouped into daily settlement batch
Fee Calculation: Transaction fees calculated and deducted
Wallet Credit: Net amount credited to your wallet
Settlement Record: Settlement batch created with unique batch ID
Notification: Webhook notification sent (if configured)

Security Considerations

⚠️

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

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

Next Steps

Wallet Balance - Check current wallet balance
Wallet Transactions - View detailed transaction history
Transaction Verification - Verify individual transactions
Single Payout - Withdraw funds via bank transfer

Wallet Transactions Overview