Chapa Developer Documentation

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}
Method: POST
Authorization: Pass your secret key as a bearer token in the request header to authorize this call.

{tx_ref} is the reference that is provided by Chapa after the payment is initiated.

Body Parameters

Parameter	Required	Type	Description
`reason`	No	string	Reason for refund
`amount`	No	string	Amount to refund. If not provided, the full transaction amount will be refunded
`meta`	No	object	Additional metadata that will be returned in the response and webhook. Can contain any custom key-value pairs
`reference`	No	string	A unique identifier for this refund request. Must be unique within your business.

cURL

JavaScript

PHP

Python

Successful Response

{
  "message": "Refund initiated successfully. Processing time: 1-3 business days",
  "status": "success",
  "data": {
    "id": 730,
    "chapa_reference": "APezQ1KKswbb",
    "bank_reference": "BLC9JI3G21",
    "amount": "1.00",
    "ref": "MERC-DIS-REF-s223VGvQFJk",
    "currency": "ETB",
    "status": "Refund Initiated",
    "reason": null,
    "merchant_reference": "OTAS379IOSHJ",
    "created_at": "2024-12-13T17:33:27.000000Z",
    "updated_at": "2024-12-13T17:33:27.000000Z"
  }
}

Response Parameters

Parameter	Type	Description
`message`	string	Response message
`status`	string	Status of the request (success/failed)
`data.id`	number	Unique refund identifier
`data.chapa_reference`	string	Chapa's reference for the original transaction
`data.bank_reference`	string	Bank reference for the refund
`data.amount`	string	Refund amount
`data.ref`	string	Refund reference ID
`data.currency`	string	Currency code (ETB, USD)
`data.status`	string	Refund status (Refund Initiated)
`data.reason`	string\|null	Reason for refund (if provided)
`data.merchant_reference`	string	Your reference for the refund
`data.created_at`	string	Timestamp when refund was created
`data.updated_at`	string	Timestamp when refund was last updated

Failed Response

{
  "message": "Refund amount cannot exceed the original transaction amount",
  "status": "failed",
  "data": null
}

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

Important: Chapa charges are non-refundable. This means we take the transaction amount plus charges from the available balance. The refund amount will be deducted from your available balance.

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

Processing Time

Refunds typically take 1-3 business days to process. The exact processing time depends on the payment method and bank processing times.

Use Cases

Customer Returns: Process refunds for returned products or services
Order Cancellations: Refund cancelled orders before fulfillment
Service Issues: Refund payments when services cannot be delivered
Partial Refunds: Refund a portion of the transaction amount

Best Practices

Verify Transaction First: Always verify the transaction exists and status before initiating a refund
Document Reasons: Provide clear reasons for refunds to maintain records
Use Unique References: Use unique merchant references for tracking refunds
Monitor Balance: Ensure sufficient balance before processing refunds
Track Refund Status: Monitor refund status to ensure completion

Next Steps

Verify Payment - Verify transaction before refunding
Get Balance - Check your available balance
Error Codes - Handle errors gracefully

Refund

On this page