The Transfer Recipients API allows you to save recipient details for faster, recurring transfers.
Overview
Instead of entering recipient details for every transfer, you can:
- Save recipients once and reuse them
- Store bank account and mobile money recipients
- Manage your recipient list
Endpoints
| Endpoint | Method | Description |
|---|
/bila/transfer-recipients | GET | List all saved recipients |
/bila/transfer-recipients/{id} | GET | Get a single recipient by ID |
/bila/transfer-recipients/bank-account | POST | Create a bank account recipient |
/bila/transfer-recipients/mobile-money | POST | Create a mobile money recipient |
Recipient Types
Bank Account Recipient
{
"id": "rec-001",
"type": "bank-account",
"accountNumber": "1234567890",
"accountName": "JOHN DOE",
"bankId": "bank-001",
"bankName": "Zambia National Commercial Bank",
"country": "zm",
"createdAt": "2024-01-15T10:30:00Z"
}
Mobile Money Recipient
{
"id": "rec-002",
"type": "mobile-money",
"phone": "0977123456",
"accountName": "JOHN DOE",
"operator": "airtel",
"country": "zm",
"createdAt": "2024-01-15T10:30:00Z"
}
Create Bank Recipient
curl -X POST "https://api.usebila.com/api/v1/bila/transfer-recipients/bank-account" \
-H "x-api-key: sk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"accountNumber": "1234567890",
"bankId": "bank-001",
"country": "zm"
}'
The account name will be automatically resolved and saved with the recipient.
Create Mobile Money Recipient
curl -X POST "https://api.usebila.com/api/v1/bila/transfer-recipients/mobile-money" \
-H "x-api-key: sk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"phone": "0977123456",
"operator": "airtel",
"country": "zm"
}'
Using Recipients in Transfers
When creating a transfer, you can use transferRecipientId instead of providing account details:
{
"accountId": "your-wallet-id",
"amount": 1000,
"reference": "payout-123",
"transferRecipientId": "rec-001",
"narration": "Monthly payout"
}
API Reference
View the interactive API reference for Recipients endpoints
