Chapa Developer Documentation

Send payouts to multiple recipients in a single API request for high-volume disbursements.

Bulk Transfer allows you to send payouts to multiple recipients in a single API request. It's designed for high-volume disbursements, such as:

Payroll payments
Vendor settlements
Affiliate commissions
Incentives and refunds at scale

Bulk transfers are processed as a batch, while each payout is tracked and settled independently.

Endpoint

POST /v2/payouts/bulk
Host: api.chapa.co

Authentication

Headers

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

Request Body

Required Fields

Field	Type	Description
`items`	array	List of payout instructions

Optional (Top-Level)

Field	Type	Description
`default_currency`	string	Default currency for items that omit `currency` (e.g. `ETB`)

Payout Item Object

Field	Type	Required	Description
`amount`	number	Yes	Amount to send
`currency`	string	Yes	ISO currency code (`ETB`, `USD`, `UGX`, `DJF` — subject to payout method)
`merchant_reference`	string	No	Unique payout reference (optional)
`reason`	string	No	Reason for payout
`account`	object	Yes	Destination account details

Account Object

Field	Description
`account_name`	Name on receiving account
`account_number`	Bank account or wallet identifier
`bank_slug`	Bank or wallet code
`bank_name`	Display name

Example Request

JSON

{
  "items": [
    {
      "amount": 500,
      "currency": "ETB",
      "account": {
        "account_number": "0968608134",
        "account_name": "Abebe Bikila",
        "bank_slug": "yaya",
        "bank_name": "telebirr Mobile Money"
      },
      "reason": "bulk payout for a business"
    },
    {
      "amount": 500,
      "currency": "ETB",
      "account": {
        "account_number": "0926760003",
        "account_name": "Abebe Bikila",
        "bank_slug": "yaya",
        "bank_name": "telebirr Mobile Money"
      }
    }
  ],
  "default_currency": "ETB"
}

cURL

curl -X POST https://api.chapa.co/v2/payouts/bulk \
  -H "Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx"
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "amount": 500,
      "currency": "ETB",
      "account": {
        "account_number": "0968608134",
        "account_name": "Abebe Bikila",
        "bank_slug": "yaya",
        "bank_name": "telebirr Mobile Money"
      },
      "reason": "bulk payout for a business"
    },
    {
      "amount": 500,
      "currency": "ETB",
      "account": {
        "account_number": "0926760003",
        "account_name": "Abebe Bikila",
        "bank_slug": "yaya",
        "bank_name": "telebirr Mobile Money"
      }
    }
  ],
  "default_currency": "ETB"
}'

JavaScript

const response = await fetch("https://api.chapa.co/v2/payouts/bulk", {
  method: "POST",
  headers: {
    "Authorization": "Bearer CHAPA_TEST_xxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "items": [
    {
      "amount": 500,
      "currency": "ETB",
      "account": {
        "account_number": "0968608134",
        "account_name": "Abebe Bikila",
        "bank_slug": "yaya",
        "bank_name": "telebirr Mobile Money"
      },
      "reason": "bulk payout for a business"
    },
    {
      "amount": 500,
      "currency": "ETB",
      "account": {
        "account_number": "0926760003",
        "account_name": "Abebe Bikila",
        "bank_slug": "yaya",
        "bank_name": "telebirr Mobile Money"
      }
    }
  ],
  "default_currency": "ETB"
})
});
const data = await response.json();

console.log(data);

Example Response

Success

{
  "status": "success",
  "message": "Bulk payout initialized successfully",
  "data": {
    "chapa_reference": "BULKPAYOUT_20251107_001",
    "total_payouts": 2,
    "status": "processing",
    "items": [
      {
        "merchant_reference": "PAY001",
        "amount": 150000,
        "currency": "ETB"
      },
      {
        "merchant_reference": "PAY002",
        "amount": 95000,
        "currency": "ETB"
      }
    ]
  },
  "created_at": "2025-11-07T11:10:00Z",
  "updated_at": "2025-11-09T11:15:00Z"
}

A successful response means the batch was accepted, not that all payouts succeeded.

Bulk Transfer Lifecycle

Batch-Level Status

Status	Meaning
`processing`	Batch accepted and processing
`completed`	All items completed successfully
`failed`	Batch-level failure (rare; item-level statuses still matter)

Item-Level Status (Delivered via Webhooks / Verification)

Status	Meaning
`pending`	Item created
`completed`	Funds delivered
`failed`	Item failed
`reversed`	Funds reversed
`blocked`	Blocked due to risk or compliance
`auth_needed`	Additional authorization required
`otp_needed`	OTP verification required

Each payout in the batch is processed independently.

Tracking Bulk Transfers

To track bulk transfers effectively:

Use the batch chapa_reference to track the overall request
Use each item merchant_reference to track individual payouts
Listen to payout webhooks for item-level status updates

Handling Partial Success

Bulk payouts may result in:

Some items succeeding
Others failing or being blocked

Recommended approach:

Update payout status per item
Do not roll back successful payouts automatically
Notify affected recipients for failed items
Retry failed payouts using new merchant references

Best Practices

Ensure each merchant_reference is globally unique
Validate all accounts before submitting bulk requests
Use Idempotency-Key for retries
Handle partial success gracefully
Store both batch and item references
Rely on webhooks for final payout states

Common Errors

HTTP	Error Code	Description
400	`INVALID_VALUE`	Invalid payout item data
404	`NOT_FOUND`	Invalid bank or account
500	`PROCESSING_FAILED`	Failed to create bulk payout

Next Steps

Payout - Single payout documentation
Bank List - Get supported banks
Webhooks - Handle payout events

Bulk Payout