Chapa Developer Documentation

Retrieve a list of all transactions created through the Chapa API with filtering and pagination.

The All Payments endpoint allows you to retrieve a list of all payments created through the Chapa API. It's commonly used for:

Transaction history and reporting
Admin dashboards
Reconciliation and auditing
Customer support investigations

You can filter transactions by status, currency, customer, reference, and date range, and paginate through large result sets.

Endpoint

GET /v2/payments
Host: api.chapa.co

Authentication

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer <PRIVATE_API_KEY>`
`Content-Type`	Yes	`application/json`

Query Parameters

All parameters are optional.

Parameter	Type	Description
`reference`	string	Filter by payment reference
`status`	string	Filter by status (`pending`, `success`, `failed`, `cancelled`, etc.)
`currency`	string	Filter by currency (`ETB`, `USD`, `UGX`, `DJF`)
`email`	string	Filter by customer email
`from`	string	Start date (ISO8601), based on `created_at`
`to`	string	End date (ISO8601), based on `created_at`
`page`	integer	Page number (default: 1)
`per_page`	integer	Records per page (default: 20)

Example Request

GET https://api.chapa.co/v2/payments?status=success&per_page=20&page=1
Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
Content-Type: application/json

Example Response

{
  "status": "success",
  "message": "Payments retrieved successfully",
  "data": {
    "items": [
      {
        "chapa_reference": "CHAPA123456789",
        "merchant_reference": "ORDER_1001",
        "payment_type": "payment link",
        "amount": 25000,
        "currency": "ETB",
        "status": "success",
        "payment_method": "card",
        "service_fee": 1000,
        "customer": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "phone_number": "251722927727"
        },
        "created_at": "2025-11-07T11:00:00Z",
        "updated_at": "2025-11-07T11:05:00Z"
      }
    ],
    "pagination": {
      "next_cursor": null,
      "prev_cursor": null,
      "limit": 20,
      "has_more": false
    }
  }
}

Response Structure

Top-Level Fields

Field	Type	Description
`status`	string	`success` or `error`
`message`	string	Summary of the result
`data`	object	Transaction items + pagination

Transaction Object (items[])

Field	Type	Description
`chapa_reference`	string	Unique Chapa payment reference
`merchant_reference`	string	Merchant-generated reference
`payment_type`	string	`API`, `Event`, `Donation`, `Hosted`, `Direct charge`, etc.
`amount`	number	Transaction amount
`currency`	string	ISO currency code
`status`	string	Payment status
`payment_method`	string	Method used (`card`, `telebirr`, etc.)
`service_fee`	number	Fee charged (if applicable)
`customer`	object	Customer details
`created_at`	string	ISO8601 creation timestamp
`updated_at`	string	ISO8601 last update timestamp