Making Payment
Payout Fees

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

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

1curl -X POST 'https://api.budpay.com/api/v2/payout_fee' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY' \4  -d '{5  "currency": "NGN",6  "amount": "100"7}'
{  "success": true,  "message": "Transfer Fee Fetched",  "fee": "10"}
Powered byXendr

Request Parameters

Header Parameters

Field NameDescriptionRequired
AuthorizationBearer token with your secret keyYes
Content-Typeapplication/jsonYes

Body Parameters

ParameterTypeRequiredDescription
currencyStringYesTransfer currency: NGN, KES, or GHS
amountStringYesTransfer amount to calculate fee for

Response Fields

FieldTypeDescription
successBooleanIndicates if fee calculation was successful
messageStringResponse message
feeStringCalculated transaction fee for the transfer

Supported Currencies

CurrencyCountryFee Structure
NGNNigeriaVariable based on amount
KESKenyaVariable based on amount
GHSGhanaVariable 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.

  1. Pre-Transfer Calculation: Always calculate fees before initiating transfers
  2. User Transparency: Display calculated fees clearly to users before confirmation
  3. Total Cost Display: Show both transfer amount and fee separately
  4. Cache Wisely: Fee structures can change; don't cache fees for extended periods
  5. Bulk Calculations: For bulk transfers, calculate total fees for accurate budgeting
  6. Balance Verification: Ensure sufficient balance for amount + fee before transfer
  7. 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

Verify TransferOverview