B2C Transfer Quick Start

Prerequisites

Merchant Account: Contact sales for a GoPay merchant account
API Key Pair: Create an Ed25519 key pair with the b2c permission — see Authentication
Funded Wallet: Transfers are debited from your merchant wallet balance
Server Environment: A backend to securely sign and send API requests

Implementation Steps

Step 1: Sign the Request
Step 2: Transfer Request
Step 3: Handle Response

B2C requests use the same Ed25519 header-based authentication as every GoPay API — only the key permission differs (b2c).Follow the Authentication guide: hash the exact body bytes, build the v1 canonical string, sign with your private key, and send the X-Public-Key, X-Signature, X-Timestamp, and X-Request-ID headers. Ready-to-use signing helpers for Node.js, Python, and Go are on that page.

Send a POST request to /api/v1/initiate-transfer:

Parameter	Type	Required	Description
`mer_id`	string	Yes	Your merchant ID
`amount`	number	Yes	Transfer amount (> 0)
`currency`	string	Yes	Currency code, e.g. `ETB`
`reason`	string	Yes	Purpose of the transfer
`receiver_phone_number`	string	Yes	Recipient phone: `09XXXXXXXX` or `+2519XXXXXXXX`
`client_reference`	string	Yes	Your unique reference for this transfer
`notify_url`	string	Yes	Absolute HTTPS URL for the settlement webhook
`bank_id`	string	Yes	Payout rail identifier (see below)

Supported payout rails:

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

On success (200 OK):

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

Save txn_id — settlement webhooks reference it
The transfer is asynchronous: initiation success means the request was accepted and your wallet debited, not that the recipient has been paid
The final result (completed / failed) arrives as a signed webhook on your notify_url — see B2C Callbacks

On error you receive the standard error shape. One code is specific to transfers: INSUFFICIENT_FUNDS (HTTP 402) means your merchant wallet balance cannot cover the transfer — top up and retry with a fresh X-Request-ID.

Getting Started

Accept Payments

Make Transfers

Webhooks

Resources

B2C Transfer Quick Start

B2C Transfer Quick Start

Prerequisites

Implementation Steps

Next Steps

API Reference

Code Examples

​B2C Transfer Quick Start

​Prerequisites

​Implementation Steps

​Next Steps

API Reference

Code Examples

B2C Transfer Quick Start

Prerequisites

Implementation Steps

Next Steps