Chapa Developer Documentation

POST /v2/subaccounts
Host: api.chapa.global
Authorization: Bearer <PRIVATE_KEY>
Content-Type: application/json

Request

Required fields: subaccount_name, account with account_number, account_name, and bank_slug, currency, split_type, and split_value.

Optional fields: account.bank_name, min_amount, max_amount, and is_primary.

split_type is percentage (whole percentages from 1 to 100) or flat (integer cents). Minimum and maximum amounts are also in cents. Subaccount creation does not require Idempotency-Key.

Example Request

For cURL, set PRIVATE_KEY in your shell. Replace the placeholders in the JavaScript example before running it.

JSON

{
  "subaccount_name": "Acme Vendor",
  "account": {
    "account_number": "251911000000",
    "account_name": "Abebe Kebede",
    "bank_slug": "telebirr",
    "bank_name": "telebirr"
  },
  "currency": "ETB",
  "split_type": "percentage",
  "split_value": 10,
  "min_amount": 100,
  "max_amount": 10000,
  "is_primary": false
}

cURL

curl -X POST 'https://api.chapa.global/v2/subaccounts' \
  -H "Authorization: Bearer $PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subaccount_name": "Acme Vendor",
  "account": {
    "account_number": "251911000000",
    "account_name": "Abebe Kebede",
    "bank_slug": "telebirr",
    "bank_name": "telebirr"
  },
  "currency": "ETB",
  "split_type": "percentage",
  "split_value": 10,
  "min_amount": 100,
  "max_amount": 10000,
  "is_primary": false
}'

JavaScript

const response = await fetch("https://api.chapa.global/v2/subaccounts", {
  method: "POST",
  headers: {
  "Authorization": "Bearer <PRIVATE_KEY>",
  "Content-Type": "application/json"
},
  body: JSON.stringify({
  "subaccount_name": "Acme Vendor",
  "account": {
    "account_number": "251911000000",
    "account_name": "Abebe Kebede",
    "bank_slug": "telebirr",
    "bank_name": "telebirr"
  },
  "currency": "ETB",
  "split_type": "percentage",
  "split_value": 10,
  "min_amount": 100,
  "max_amount": 10000,
  "is_primary": false
})
});
const data = await response.json();

console.log(data);

Example Response

200 Success

{
  "status": "success",
  "message": "Subaccount created successfully",
  "data": {
    "subaccount_reference": "SUB_566492527h",
    "created_at": "2026-10-05T09:30:00Z",
    "updated_at": "2026-10-05T09:30:00Z"
  }
}

400 Error

{
  "status": "error",
  "message": "Flat split value must be greater than 0",
  "error": {
    "code": "INVALID_VALUE",
    "details": null
  }
}

401 Error

{
  "status": "error",
  "message": "Invalid API key or User does not exist",
  "error": {
    "code": "UNAUTHORIZED",
    "details": null
  }
}

403 Error

{
  "status": "error",
  "message": "API key environment does not match business environment.",
  "error": {
    "code": "INVALID_VALUE",
    "details": null
  }
}

409 Error

{
  "status": "error",
  "message": "A subaccount with this bank account already exists for this business",
  "error": {
    "code": "INVALID_STATE",
    "details": null
  }
}

500 Error

{
  "status": "error",
  "message": "Failed to create subaccount",
  "error": {
    "code": "PROCESSING_FAILED",
    "details": null
  }
}

Store data.subaccount_reference and reuse it in payment split rules.

Create Subaccount

Request

On this page