Making Payment
Single Transfer

Single Payout (Bank Transfer)

Initiate direct bank transfers to send funds to bank accounts across Nigeria (NGN), Kenya (KES), and Ghana (GHS). This endpoint processes payouts with real-time status updates.

Endpoint

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

Sample Requests

Nigeria (NGN) Transfer

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

1curl -X POST 'https://api.budpay.com/api/v2/bank_transfer' \2  -H 'Encryption: Signature_HMAC-SHA-512' \3  -H 'Content-Type: application/json' \4  -H 'Authorization: Bearer YOUR_SECRET_KEY' \5  -d '{6  "currency": "NGN",7  "amount": "100",8  "bank_code": "000013",9  "bank_name": "GUARANTY TRUST BANK",10  "account_number": "0050883605",11  "narration": "Test transfer",12  "meta_data": [13    {14      "sender_name": "Nium Consult",15      "sender_address": "New Orleans, USA"16    }17  ]18}'
{  "success": true,  "message": "Transfer successfully logged and Processing",  "data": {    "reference": "trf_11044f068j1604",    "currency": "NGN",    "amount": "100",    "fee": "10",    "bank_code": "000013",    "bank_name": "GUARANTY TRUST BANK",    "account_number": "0050883605",    "account_name": "OYENIYI TOLULOPE OYEBIYI",    "narration": "Test transfer",    "domain": "test",    "status": "pending",    "updated_at": "2022-03-29T02:51:01.000000Z",    "created_at": "2022-03-29T02:51:01.000000Z"  }}
Powered byXendr

Request Parameters

Header Parameters

Field NameDescriptionRequired
AuthorizationBearer token with your secret keyYes
EncryptionSignature_HMAC-SHA-512 for request encryptionYes
Content-Typeapplication/jsonYes

Body Parameters

ParameterTypeRequiredDescription
currencyStringYesTransfer currency: NGN, KES, or GHS
amountStringYesTransfer amount (excluding fees)
bank_codeStringYesBank code from bank list API
bank_nameStringYesBank name
account_numberStringYesRecipient bank account number
narrationStringYesTransfer description/purpose
paymentModeStringNoPayment mode (e.g., momo for Kenya)
meta_dataArrayNoAdditional metadata (sender info, etc.)

Response Fields

FieldTypeDescription
successBooleanIndicates if transfer was initiated successfully
messageStringResponse message
data.referenceStringUnique transfer reference ID
data.currencyStringTransfer currency
data.amountStringTransfer amount
data.feeStringTransaction fee charged
data.bank_codeStringRecipient bank code
data.bank_nameStringRecipient bank name
data.account_numberStringRecipient account number
data.account_nameStringVerified account holder name
data.narrationStringTransfer description
data.domainStringEnvironment: test or live
data.statusStringTransfer status: pending, success, failed
data.created_atStringTransfer creation timestamp
data.updated_atStringLast update timestamp

Transfer Status

StatusDescription
pendingTransfer initiated and being processed
successTransfer completed successfully
failedTransfer failed (insufficient funds, invalid account, etc.)

Supported Currencies

CurrencyCountryPayment Mode
NGNNigeriaBank Transfer
KESKenyaBank Transfer / Mobile Money
GHSGhanaBank Transfer

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": {
        "amount": ["The amount field is required"],
        "account_number": ["Invalid account number"]
    }
}

500 Server Error

{
    "success": false,
    "message": "Transfer processing failed"
}

Best Practices

Tip: Always verify account details using the account name validation endpoint before initiating transfers to prevent errors.

  1. Validate Account First: Use the account name validation endpoint before transfers
  2. Verify Status: Always check transfer status using the reference ID
  3. Handle Webhooks: Implement webhook handlers for real-time status updates
  4. Idempotency: Store reference IDs to prevent duplicate transfers
  5. Error Handling: Implement retry logic for failed transfers
  6. Balance Check: Ensure sufficient wallet balance before transfers
  7. Test Mode: Test thoroughly in sandbox before going live

Security Considerations

⚠️

Security: The Encryption header with HMAC-SHA-512 signature is required for all bank transfer requests.

  • HMAC Signature: Always include the Encryption: Signature_HMAC-SHA-512 header
  • Server-Side Only: Never expose secret keys in frontend code
  • HTTPS Only: All requests must use secure HTTPS connections
  • Validate Webhooks: Verify webhook signatures before processing
  • Log Transfers: Maintain audit logs of all transfer requests

Next Steps

Account Name ValidationBulk Transfer