Bulk Payout (Bulk Bank Transfer)

Process multiple bank transfers in a single API request. Ideal for batch payments like salaries, vendor payments, and commission disbursements across multiple recipients.

Endpoint

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

Sample Request

curl https://api.budpay.com/api/v2/bulk_bank_transfer \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Encryption: Signature_HMAC-SHA-512" \
-H "Content-Type: application/json" \
-d '{
    "currency": "NGN",
    "transfers": [
        {
            "amount": "200",
            "bank_code": "000013",
            "bank_name": "GUARANTY TRUST BANK",
            "account_number": "0050883605",
            "narration": "January Salary"
        },
        {
            "amount": "100",
            "bank_code": "000013",
            "bank_name": "GUARANTY TRUST BANK",
            "account_number": "0050883605",
            "narration": "February Salary"
        },
        {
            "amount": "100",
            "bank_code": "000013",
            "bank_name": "GUARANTY TRUST BANK",
            "account_number": "0050883605",
            "narration": "March Salary"
        }
    ]
}' \
-X POST

Sample Response

{
    "success": true,
    "message": "3 Transfers queued",
    "data": [
        {
            "reference": "trf_j51m4695fk57nf",
            "currency": "NGN",
            "amount": "200",
            "fee": "10",
            "bank_code": "000013",
            "bank_name": "GUARANTY TRUST BANK",
            "account_number": "0050883605",
            "account_name": "OYENIYI TOLULOPE OYEBIYI",
            "narration": "January Salary",
            "domain": "test",
            "status": "pending",
            "updated_at": "2022-03-30T00:03:12.000000Z",
            "created_at": "2022-03-30T00:03:12.000000Z"
        },
        {
            "reference": "trf_1h1x3v5400n612",
            "currency": "NGN",
            "amount": "100",
            "fee": "10",
            "bank_code": "000013",
            "bank_name": "GUARANTY TRUST BANK",
            "account_number": "0050883605",
            "account_name": "OYENIYI TOLULOPE OYEBIYI",
            "narration": "February Salary",
            "domain": "test",
            "status": "pending",
            "updated_at": "2022-03-30T00:03:13.000000Z",
            "created_at": "2022-03-30T00:03:13.000000Z"
        },
        {
            "reference": "trf_f9098ac5272653",
            "currency": "NGN",
            "amount": "100",
            "fee": "10",
            "bank_code": "000013",
            "bank_name": "GUARANTY TRUST BANK",
            "account_number": "0050883605",
            "account_name": "OYENIYI TOLULOPE OYEBIYI",
            "narration": "March Salary",
            "domain": "test",
            "status": "pending",
            "updated_at": "2022-03-30T00:03:13.000000Z",
            "created_at": "2022-03-30T00:03:13.000000Z"
        }
    ]
}

Try it out

Request Parameters

Header Parameters

Body Parameters

Transfer Object Parameters

Response Fields

Transfer Object Response Fields

Transfer Status

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

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"],
        "transfers": ["The transfers field must be an array"]
    }
}

500 Server Error

{
    "success": false,
    "message": "Bulk transfer processing failed"
}

Best Practices

1. Validate Accounts: Verify all account details using account name validation before bulk transfer
2. Batch Size: Keep batch sizes reasonable (recommended: 100-500 transfers per request)
3. Track References: Store all reference IDs for individual transfer tracking
4. Monitor Status: Use webhooks to track individual transfer completion
5. Error Handling: Implement retry logic for failed transfers within the batch
6. Balance Check: Ensure sufficient wallet balance for total batch amount plus fees
7. Idempotency: Implement unique identifiers to prevent duplicate batch submissions
8. Test First: Always test bulk transfers in sandbox with small batches

Bulk Transfer Workflow

1. Submit Batch: Send array of transfers in single API request
2. Queue Confirmation: API returns immediately with all transfer references
3. Async Processing: Transfers process independently in the background
4. Status Updates: Each transfer updates individually (webhook notifications)
5. Verification: Track each transfer using its unique reference

Security Considerations

• 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 status updates
• Audit Logs: Maintain detailed logs of all bulk transfer requests
• Data Privacy: Never log or store sensitive account details in plain text

Next Steps

• Single Payout - Process individual bank transfers
• Account Name Validation - Verify accounts before transfer
• Bank List - Get supported banks for each currency
• Transaction Verification - Verify individual transfer status
• Webhooks - Set up real-time status notifications