Chapa Developer Documentation

Payouts allow you to send money from your Chapa balance to a bank account or mobile money wallet.

This feature is commonly used for:

Vendor payouts
Customer withdrawals
Partner settlements
Internal fund disbursement

Payouts are asynchronous. A successful API response means the payout was created, not completed.

Endpoint

POST /v2/payouts
Host: api.chapa.global

Authentication

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer <PRIVATE_API_KEY>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Prevents duplicate payout creation on retries

Request Body

Required Fields

Field	Type	Description
`amount`	number	Amount to transfer
`currency`	string	ISO currency code (`USD`, `UGX`, `ETB`, `DJF`, availability depends on payout method)
`account`	object	Destination account details

Optional Fields

Field	Type	Description
`merchant_reference`	string	Merchant-generated payout reference (optional)
`reason`	string	Description of the payout
`meta`	object	Custom metadata for internal tracking

Account Object

Field	Description
`account_name`	Name on the receiving account
`account_number`	Bank account or wallet identifier
`bank_slug`	Short bank or wallet identifier
`bank_name`	Display name of the bank or wallet

Example Request

JSON

{
  "amount": 500,
  "currency": "ETB",
  "account": {
    "account_number": "0926760003",
    "account_name": "Abebe Bikila",
    "bank_slug": "yaya",
    "bank_name": "yaya"
  },
  "reason": "Vendor payout for services",
  "meta": {
    "a": "b"
  }
}

cURL

curl -X POST https://api.chapa.global/v2/payouts \
  -H "Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx"
  -H "Content-Type: application/json" \
  -d '{
  "amount": 500,
  "currency": "ETB",
  "account": {
    "account_number": "0926760003",
    "account_name": "Abebe Bikila",
    "bank_slug": "yaya",
    "bank_name": "yaya"
  },
  "reason": "Vendor payout for services",
  "meta": {
    "a": "b"
  }
}'

JavaScript

const response = await fetch("https://api.chapa.global/v2/payouts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer CHAPA_TEST_xxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "amount": 500,
  "currency": "ETB",
  "account": {
    "account_number": "0926760003",
    "account_name": "Abebe Bikila",
    "bank_slug": "yaya",
    "bank_name": "yaya"
  },
  "reason": "Vendor payout for services",
  "meta": {
    "a": "b"
  }
})
});
const data = await response.json();

console.log(data);

Example Response

Success

{
  "status": "success",
  "message": "Payout initialized successfully",
  "data": {
    "chapa_reference": "CP123456789",
    "status": "pending"
  },
  "created_at": "2025-11-07T11:06:00Z",
  "updated_at": "2025-11-08T11:06:00Z"
}

At this stage, the payout is pending, not completed.

Payout Status Lifecycle

A payout may move through the following states:

Status	Meaning
`pending`	Created but not yet processed
`processing`	Being processed
`success` / `completed`	Funds delivered successfully
`failed`	Payout failed
`blocked`	Blocked due to risk or compliance
`auth_needed`	Additional authorization required
`otp_needed`	OTP verification required
`reversed`	Funds reversed after processing