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

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

cURLJavascriptPythonGo

More

cURL

More

Try it

1curl -X POST 'https://api.budpay.com/api/v2/bulk_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  "transfers": [8    {9      "amount": "200",10      "bank_code": "000013",11      "bank_name": "GUARANTY TSUST BANK",12      "account_number": "0050883605",13      "narration": "January Salary"14    },15    {16      "amount": "100",17      "bank_code": "000013",18      "bank_name": "GUARANTY TSUST BANK",19      "account_number": "0050883605",20      "narration": "February Salary"21    },22    {23      "amount": "100",24      "bank_code": "000013",25      "bank_name": "GUARANTY TRUST BANK",26      "account_number": "0050883605",27      "narration": "March Salary"28    }29  ]30}'

200 OK

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

Powered by

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