Wallet and Settlement
Settlements

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

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

1curl -X GET 'https://api.budpay.com/api/v2/settlement' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'
{  "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  }}
Powered byXendr

Request Parameters

Header Parameters

Field NameDescriptionRequired
AuthorizationBearer token with your secret keyYes

Response Fields

FieldTypeDescription
statusBooleanIndicates if request was successful
messageStringResponse message
dataArrayArray of settlement batch objects
meta.totalIntegerTotal number of settlements

Settlement Object Fields

FieldTypeDescription
idIntegerInternal settlement ID
batchidStringUnique settlement batch identifier
currencyStringSettlement currency (NGN, KES, GHS, USD)
total_amountStringTotal transaction amount before fees
settled_amountStringAmount credited to wallet after fees
domainStringEnvironment: test or live
statusStringSettlement status
subaccountStringSubaccount ID (if applicable)
created_atStringSettlement creation timestamp
updated_atStringLast update timestamp

Settlement Status

StatusDescription
successSettlement completed and credited to wallet
pendingSettlement being processed
failedSettlement 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.

  1. Regular Monitoring: Check settlement history regularly for accounting purposes
  2. Reconciliation: Match settlement batch IDs with wallet transactions
  3. Fee Tracking: Monitor fee amounts for cost analysis
  4. Record Keeping: Store settlement data for financial records and audits
  5. Verify Amounts: Cross-check settled amounts with expected revenue
  6. Date Tracking: Track settlement dates for cash flow planning
  7. 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

Endpoint: GET https://api.budpay.com/api/v2/settlement/details/1166806529561

1curl -X GET 'https://api.budpay.com/api/v2/settlement/details/1166806529561' \2  -H 'Authorization: Bearer YOUR_SECRET_KEY'
{  "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"    }  ]}
Powered byXendr

Request Parameters

ParameterTypeRequiredDescription
batchidStringYesUnique settlement batch identifier

Response Fields

Settlement Data:

FieldTypeDescription
data.idIntegerInternal settlement ID
data.batchidStringUnique settlement batch identifier
data.currencyStringSettlement currency
data.total_amountStringTotal transaction amount before fees
data.settled_amountStringAmount credited to wallet after fees
data.domainStringEnvironment: test or live
data.statusStringSettlement status
data.created_atStringSettlement creation timestamp
data.updated_atStringLast update timestamp

Transaction Fields:

FieldTypeDescription
idIntegerTransaction ID
currencyStringTransaction currency
amountStringTransaction amount
feesStringTransaction fees charged
requested_amountStringNet amount after fees
referenceStringTransaction reference ID
channelStringPayment channel (transfer, card, etc.)
domainStringEnvironment: test or live
statusStringTransaction status
customer_idIntegerCustomer identifier
created_atStringTransaction creation timestamp
paid_atStringPayment 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:

  1. Transaction Complete: Customer payment successfully processed
  2. Batch Collection: Transactions grouped into daily settlement batch
  3. Fee Calculation: Transaction fees calculated and deducted
  4. Wallet Credit: Net amount credited to your wallet
  5. Settlement Record: Settlement batch created with unique batch ID
  6. 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 TransactionsOverview