Get Virtual Account Credit History

Retrieve a list of all credit (deposit) transactions performed on a virtual account.

The Credit History endpoint returns a list of all credit (deposit) transactions performed on a virtual account.

Use this endpoint to:

Show wallet top-up history to users
Reconcile deposits with your internal funding records
Audit balance changes and trace funding sources
Investigate customer support issues

Endpoint

GET /v2/virtual-accounts/{virtual_account_id}/credits
Host: api.chapa.co

Authentication

Headers

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

Path Parameter

Parameter	Required	Description
`virtual_account_id`	Yes	Unique virtual account identifier

Query Parameters (Optional)

Parameter	Type	Description
`from`	string	Start date (ISO8601) filter
`to`	string	End date (ISO8601) filter
`page`	integer	Page number (default: 1)
`per_page`	integer	Records per page (default: 20)
`merchant_reference`	string	Filter by merchant reference

Example Request

cURL

curl -X GET https://api.chapa.co/v2/virtual-accounts/VA_ABC123456/credits?per_page=20&page=1 \
  -H "Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx"

JavaScript

const response = await fetch("https://api.chapa.co/v2/virtual-accounts/VA_ABC123456/credits?per_page=20&page=1", {
  method: "GET",
  headers: {
    "Authorization": "Bearer CHAPA_TEST_xxxxxxxxxxxxx"
  }
});
const data = await response.json();

console.log(data);

Example Response

{
  "status": "success",
  "message": "Credit history retrieved successfully",
  "data": {
    "items": [
      {
        "deposit_reference": "DEP_TRX_987654",
        "merchant_reference": "DEP_001",
        "amount": 5000,
        "currency": "ETB",
        "reason": "Wallet top-up",
        "meta": {
          "order_id": "ORD_99887",
          "customer_id": "CUST_12345"
        },
        "balance_before": 7500,
        "balance_after": 12500,
        "created_at": "2025-11-07T13:10:00Z"
      }
    ],
    "pagination": {
      "next_cursor": null,
      "prev_cursor": null,
      "limit": 20,
      "has_more": false
    }
  }
}

Response Fields

Credit History Item

Field	Type	Description
`deposit_reference`	string	Unique deposit transaction reference
`merchant_reference`	string	Merchant-generated reference (if provided)
`amount`	number	Amount credited
`currency`	string	Currency
`reason`	string	Reason or description
`meta`	object	Custom metadata
`balance_before`	number	Balance before credit
`balance_after`	number	Balance after credit
`created_at`	string	Timestamp

Pagination

Field	Type	Description
`next_cursor`	string	Cursor token for next page
`prev_cursor`	string	Cursor token for previous page
`limit`	integer	Items returned
`has_more`	boolean	Whether more results exist

Best Practices

Filter by date range for faster results
Use merchant_reference and Idempotency-Key when depositing to prevent duplicates
Store deposit_reference for reconciliation
Use meta to connect deposits to your internal objects (order_id, customer_id, etc.)

Common Errors

HTTP	Error Code	Description
404	`NOT_FOUND`	Virtual account not found
500	`PROCESSING_FAILED`	Failed to fetch credit history

Next Steps

Create Virtual Account - Create a new account
Get Virtual Account - Retrieve account details
Get Debit History - View deduction transactions

Get Virtual Account Credit History

On this page