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 Field

Field	Type	Description
`items`	array	List of payout instructions

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	Yes	Unique payout reference
`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

POST https://api.chapa.co/v2/payouts/bulk
Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
Content-Type: application/json

{
  "items": [
    {
      "amount": 150000,
      "currency": "ETB",
      "merchant_reference": "PAY001",
      "reason": "Vendor payment",
      "account": {
        "account_name": "Customer Name",
        "account_number": "123567890987",
        "bank_slug": "cbe",
        "bank_name": "Commercial Bank of Ethiopia"
      }
    },
    {
      "amount": 95000,
      "currency": "ETB",
      "merchant_reference": "PAY002",
      "reason": "Freelance design work",
      "account": {
        "account_name": "Customer Name",
        "account_number": "123567890987",
        "bank_slug": "cbe",
        "bank_name": "Commercial Bank of Ethiopia"
      }
    }
  ],
  "meta": {
    "order_id": "ORD-7823",
    "requested_by": "customer_support"
  }
}

Example Response

{
  "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