Transfer API Reference

This reference documents the B2C (business-to-customer) transfer initiation API.

Base URL

The B2C API is a separate deployment from the C2B payment API — use the transfers base URL provided during onboarding. Because the host is part of the signed canonical string, signatures are bound to the exact host and environment you call.

Authentication

Requests are authenticated with a detached Ed25519 signature over the v1 canonical string, sent via the X-Public-Key, X-Signature, X-Timestamp, and X-Request-ID headers. Your API key must carry the b2c permission. See Authentication for the full scheme, signing helpers, and the replay/rate-limit rules that apply to every request.

Initiate Transfer

Creates a payout transaction and debits your merchant wallet. The payout itself settles asynchronously; the final result is delivered by webhook. Endpoint

POST /api/v1/initiate-transfer

Request Body

Parameter	Type	Required	Description
`mer_id`	string	Yes	Your merchant ID
`amount`	number	Yes	Transfer amount; must be > 0 and at most 10,000,000
`currency`	string	Yes	One of: `ETB`, `KES`, `USD`, `EUR`, `GBP`
`reason`	string	Yes	Purpose of the transfer (included in the settlement webhook)
`receiver_phone_number`	string	Yes	Ethiopian mobile number: `09XXXXXXXX` or `+2519XXXXXXXX`
`client_reference`	string	Yes	Your unique reference for reconciliation
`notify_url`	string	Yes	Absolute HTTPS URL that receives the settlement webhook
`bank_id`	string	Yes	Payout rail: `"1"`–`"5"` (see table below)

Validation failures are accumulated — the error message lists every failing field.

Payout Rails

`bank_id`	Rail
`1`	Telebirr
`2`	CBE Birr
`3`	Awash Bank
`4`	Dashen Bank
`5`	Bank of Abyssinia

Response

Success (200 OK)
Error (non-2xx)

{
    "message": "B2C transaction initiated successfully",
    "txn_id": "b2c_tx_6fcb15a983c54a7e97b1",
    "status": "pending"
}

A 200 means the transaction was recorded and your wallet debited. Track txn_id — the settlement webhook references it.

All errors share the standard shape — see Errors for the full code taxonomy:

{
    "error": {
        "code": "INSUFFICIENT_FUNDS",
        "message": "insufficient funds",
        "requestId": "req_..."
    }
}

INSUFFICIENT_FUNDS (HTTP 402) is specific to transfers: your merchant wallet balance cannot cover the payout.

Retrying transfers moves money — be careful. On UPSTREAM_TIMEOUT or UPSTREAM_UNAVAILABLE, check for a settlement webhook or contact support with the requestId before resubmitting, and always use a stable client_reference so duplicates can be detected during reconciliation. The wallet debit itself is idempotent per transaction, so a single accepted transfer can never double-charge.

Transfer Statuses

Delivered via webhook (see B2C Callbacks):

Status	Description
`completed`	Payout settled to the recipient
`failed`	Payout failed; funds are returned to your wallet
`expired`	Payout expired before settlement
`cancelled`	Payout was cancelled

Getting Started

Accept Payments

Make Transfers

Webhooks

Resources

Transfer API Reference

Transfer API Reference

Base URL

Authentication

Initiate Transfer

Request Body

Payout Rails

Response

Transfer Statuses

​Transfer API Reference

​Base URL

​Authentication

​Initiate Transfer

​Request Body

​Payout Rails

​Response

​Transfer Statuses

Transfer API Reference

Base URL

Authentication

Initiate Transfer

Request Body

Payout Rails

Response

Transfer Statuses