Chapa Developer Documentation

GET /v2/subaccounts
Host: api.chapa.global
Authorization: Bearer <PRIVATE_KEY>

The optional limit query parameter defaults to 10. The collection describes optional filters and cursor pagination but does not enumerate the filter or cursor request parameters.

Example Request

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

cURL

curl -X GET 'https://api.chapa.global/v2/subaccounts?limit=10' \
  -H "Authorization: Bearer $PRIVATE_KEY"

JavaScript

const response = await fetch("https://api.chapa.global/v2/subaccounts?limit=10", {
  method: "GET",
  headers: {
  "Authorization": "Bearer <PRIVATE_KEY>"
},
});
const data = await response.json();

console.log(data);

Example Response

200 Success

{
  "status": "success",
  "message": "Subaccounts retrieved successfully",
  "data": {
    "items": [
      {
        "subaccount_reference": "SUB_566492527h",
        "subaccount_name": "Acme Vendor",
        "account": {
          "account_number": "0900****71",
          "account_name": "Abebe Kebede",
          "bank_slug": "telebirr",
          "bank_name": "telebirr"
        },
        "country": "ET",
        "currency": "ETB",
        "split_type": "percentage",
        "split_value": 10,
        "min_amount": 100,
        "max_amount": 10000,
        "is_active": true,
        "meta": {},
        "created_at": "2026-10-05T09:30:00Z",
        "updated_at": "2026-10-05T09:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "next_cursor": null,
      "prev_cursor": null,
      "has_more": false
    }
  }
}

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
  }
}

500 Error

{
  "status": "error",
  "message": "Failed to fetch subaccounts",
  "error": {
    "code": "PROCESSING_FAILED",
    "details": null
  }
}

data.items contains subaccounts and their nested account details. data.pagination includes limit, next_cursor, prev_cursor, and has_more.

List Subaccounts