Refund

Refund

This documentation provides detailed information on how to process refunds using our API. It includes steps for initiating a refund, required parameters, and handling responses.

Initiating Refund

Endpoint https://api.chapa.co/v1/refund/<tx_ref>

<tx_ref> is the reference that is provided by the chapa after the payment is initiated.

Method POST

  • Authorization : Pass your secret key as a bearer token in the request header to authorize this call.

Body Params

ParameterRequiredTypeDescription
reasonnostringReason for refund
amountnostringAmount to refund. If not provided, the full transaction amount will be refunded
metanoobjectAdditional metadata that will be returned in the response and webhook. Can contain any custom key-value pairs
referencenostringA unique identifier for this refund request. Must be unique within your business.
1import http.client
2  
3  conn = http.client.HTTPSConnection("api.chapa.co")
4  payload = 'reason=accidental purchase&amount=1000&meta[customer_id]=123&meta[reference]=REF123'
5  headers = {
6    'Content-Type': 'application/x-www-form-urlencoded',
7    'Authorization': 'Bearer Bearer CHASECK_TEST-xxxxxxxxxxxxxxxx'
8  }
9  conn.request("POST", "/v1/refund/APezQ1KKswbb", payload, headers)
10  res = conn.getresponse()
11  data = res.read()
12  print(data.decode("utf-8"))

After a successful request, the response includes a ref_id. Use this ref_id with the verify endpoint to check the refund status.

Verify refund

To check the status of a refund, call the verify endpoint:

Endpoint https://api.chapa.co/v1/refund/:ref_id/verify

:ref_id is the reference of the refund (e.g. data.ref_id from the initiate refund response).

Method GET

  • Authorization: Pass your secret key as a bearer token in the request header to authorize this call.

Response

The verify endpoint returns a response like this:

{
  "message": "Refund verified successfully",
  "status": "success",
  "data": {
    "amount": 1,
    "currency": "USD",
    "ref_id": "MERC-DIS-REF-HnIITWNXjNB",
    "payment_reference": "CGRMuqd8ECClEiS",
    "merchant_reference": null,
    "status": "initiated",
    "created_at": "2025-06-09T15:45:46.000000Z",
    "updated_at": "2025-06-09T15:45:46.000000Z"
  }
}

Refund statuses

The refund goes through three possible statuses in data.status:

StatusDescription
initiatedThe refund request was accepted. This is the first step—the refund is now being processed.
refundedThe refund completed successfully. The amount has been returned to the customer.
reversedThe refund could not be completed (e.g. due to a failure during processing). The amount was returned to your Chapa account balance.

Track the refund by calling the verify endpoint with ref_id or via webhooks; when processing finishes, the status will change to either refunded or reversed.

NB – If amount is not provided, we will refund the full transaction amount.

Chapa charges are non-refundable. The transaction amount plus charges are taken from your available balance—the refund amount will be deducted from your available balance.

ℹ️

Refer to our Error Codes page for all responses for this request.

Fraud PreventionError