Payout Fees

Calculate the transaction fee for a bank transfer before initiating the payout. This helps you determine the total cost and display accurate fee information to users.

Endpoint

POST https://api.budpay.com/api/v2/payout_fee

Sample Request

curl https://api.budpay.com/api/v2/payout_fee \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
    "currency": "NGN",
    "amount": "100"
}' \
-X POST

Sample Response

{
    "success": true,
    "message": "Transfer Fee Fetched",
    "fee": "10"
}

Try it out

Request Parameters

Header Parameters

Field Name	Description	Required
Authorization	Bearer token with your secret key	Yes
Content-Type	`application/json`	Yes

Body Parameters

Parameter	Type	Required	Description
`currency`	String	Yes	Transfer currency: `NGN`, `KES`, or `GHS`
`amount`	String	Yes	Transfer amount to calculate fee for

Response Fields

Field	Type	Description
`success`	Boolean	Indicates if fee calculation was successful
`message`	String	Response message
`fee`	String	Calculated transaction fee for the transfer

Supported Currencies

Currency	Country	Fee Structure
NGN	Nigeria	Variable based on amount
KES	Kenya	Variable based on amount
GHS	Ghana	Variable based on amount

Note: Fee structures may vary by currency and amount. Always call this endpoint to get the accurate fee before processing transfers.

Error Handling

400 Bad Request

{
    "success": false,
    "message": "Invalid request parameters"
}

401 Unauthorized

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

422 Validation Error

{
    "success": false,
    "message": "Validation error",
    "errors": {
        "currency": ["The currency field is required"],
        "amount": ["The amount must be a valid number"]
    }
}

Best Practices

Tip: Always fetch and display the fee to users before initiating transfers to ensure transparency and prevent surprises.

Pre-Transfer Calculation: Always calculate fees before initiating transfers
User Transparency: Display calculated fees clearly to users before confirmation
Total Cost Display: Show both transfer amount and fee separately
Cache Wisely: Fee structures can change; don't cache fees for extended periods
Bulk Calculations: For bulk transfers, calculate total fees for accurate budgeting
Balance Verification: Ensure sufficient balance for amount + fee before transfer
Error Handling: Implement fallback if fee calculation fails

Fee Calculation Examples

Single Transfer

Transfer Amount: NGN 100
Fee: NGN 10
Total Deducted: NGN 110

Bulk Transfer

3 transfers of NGN 100 each
Fee per transfer: NGN 10
Total Amount: NGN 300
Total Fees: NGN 30
Total Deducted: NGN 330

Integration Tips

💡

Integration: Call this endpoint before displaying transfer confirmation to users. Include the fee in your UI to provide complete cost visibility.

Real-Time Calculation: Fetch fee when user enters transfer amount
Confirmation Screen: Display breakdown of amount + fee = total
Budget Planning: Use for calculating costs in bulk transfer planning
Financial Records: Store fee information for accounting and reconciliation

Next Steps

Single Payout - Initiate individual bank transfers
Bulk Payout - Process multiple transfers in batch
Verify Transfer - Check transfer status
Wallet Balance - Check available balance

Verify Transfer Overview