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

curl https://api.budpay.com/api/v2/bank_transfer \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Encryption: Signature_HMAC-SHA-512" \
-H "Content-Type: application/json" \
-d '{
    "currency": "NGN",
    "amount": "100",
    "bank_code": "000013",
    "bank_name": "GUARANTY TRUST BANK",
    "account_number": "0050883605",
    "narration": "Test transfer",
    "meta_data": [
        {
            "sender_name": "Nium Consult",
            "sender_address": "New Orleans, USA"
        }
    ]
}' \
-X POST

Sample Response

{
    "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"
    }
}

Try it out

Request Parameters

Header Parameters

Field Name	Description	Required
Authorization	Bearer token with your secret key	Yes
Encryption	`Signature_HMAC-SHA-512` for request encryption	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 (excluding fees)
`bank_code`	String	Yes	Bank code from bank list API
`bank_name`	String	Yes	Bank name
`account_number`	String	Yes	Recipient bank account number
`narration`	String	Yes	Transfer description/purpose
`paymentMode`	String	No	Payment mode (e.g., `momo` for Kenya)
`meta_data`	Array	No	Additional metadata (sender info, etc.)

Response Fields

Field	Type	Description
`success`	Boolean	Indicates if transfer was initiated successfully
`message`	String	Response message
`data.reference`	String	Unique transfer reference ID
`data.currency`	String	Transfer currency
`data.amount`	String	Transfer amount
`data.fee`	String	Transaction fee charged
`data.bank_code`	String	Recipient bank code
`data.bank_name`	String	Recipient bank name
`data.account_number`	String	Recipient account number
`data.account_name`	String	Verified account holder name
`data.narration`	String	Transfer description
`data.domain`	String	Environment: `test` or `live`
`data.status`	String	Transfer status: `pending`, `success`, `failed`
`data.created_at`	String	Transfer creation timestamp
`data.updated_at`	String	Last update timestamp

Transfer Status

Status	Description
`pending`	Transfer initiated and being processed
`success`	Transfer completed successfully
`failed`	Transfer failed (insufficient funds, invalid account, etc.)

Supported Currencies

Currency	Country	Payment Mode
NGN	Nigeria	Bank Transfer
KES	Kenya	Bank Transfer / Mobile Money
GHS	Ghana	Bank 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.

Validate Account First: Use the account name validation endpoint before transfers
Verify Status: Always check transfer status using the reference ID
Handle Webhooks: Implement webhook handlers for real-time status updates
Idempotency: Store reference IDs to prevent duplicate transfers
Error Handling: Implement retry logic for failed transfers
Balance Check: Ensure sufficient wallet balance before transfers
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 Validation - Verify account details before transfer
Bank List - Get supported banks for each currency
Transaction Verification - Verify transfer status
Webhooks - Set up real-time status notifications

Account Name Validation Bulk Transfer