Refunds

A Refund allows a merchant to return funds to a customer for a successfully completed payment.

Chapa supports both full and partial refunds through a secure, API-driven flow.

Refunds help you:

• Resolve customer complaints
• Prevent disputes and chargebacks
• Maintain a healthy risk profile

When Can You Issue a Refund?

You can create a refund only if the payment:

• Has status success
• Is not pending, failed, cancelled, or incomplete
• Has not already been fully refunded

Attempting to refund an invalid payment state will result in an error.

Refund Types

1. Full Refund

• Refunds the entire payment amount
• Triggered when amount is not provided

2. Partial Refund

• Refunds part of the original amount
• Triggered when amount is provided
• Multiple partial refunds are allowed until the full amount is reached

Create a Refund

Endpoint

POST /v2/refunds
Host: api.chapa.global

Headers

Request Body

Example Request (Partial Refund)

{
  "payment_reference": "CHp4OlUAjucj",
  "amount": 100,
  "reason": "Customer returned the product",
  "meta": {
    "order_id": "ORD-7823",
    "requested_by": "customer_support"
  }
}

curl -X POST https://api.chapa.global/v2/refunds \
  -H "Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx"
  -H "Content-Type: application/json" \
  -d '{
  "payment_reference": "CHp4OlUAjucj",
  "amount": 100,
  "reason": "Customer returned the product",
  "meta": {
    "order_id": "ORD-7823",
    "requested_by": "customer_support"
  }
}'

const response = await fetch("https://api.chapa.global/v2/refunds", {
  method: "POST",
  headers: {
    "Authorization": "Bearer CHAPA_TEST_xxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "payment_reference": "CHp4OlUAjucj",
  "amount": 100,
  "reason": "Customer returned the product",
  "meta": {
    "order_id": "ORD-7823",
    "requested_by": "customer_support"
  }
})
});
const data = await response.json();

console.log(data);

Example Response

{
  "status": "success",
  "message": "Refund processed successfully",
  "data": {
    "chapa_reference": "RFND987654321",
    "payment_reference": "CHp4OlUAjucj",
    "amount": 100,
    "currency": "ETB",
    "status": "completed",
    "created_at": "2025-11-07T14:32:00Z",
    "updated_at": "2025-11-08T14:45:00Z"
  }
}

Refund Lifecycle

Refunds typically move through these states:

Final state is confirmed via webhooks or verification.

Verify a Refund

Endpoint

GET /v2/refunds/{reference}/verify

Use this to confirm the final status of a refund.

Get Refunds (List)

Endpoint

GET /v2/refunds

Supports filtering by:

• Refund reference
• Payment reference
• Status
• Date range

Webhook Events for Refunds

Refund-related webhook events include:

• payment.partially_refunded
• payment.fully_refunded

Example

{
  "event": "payment.partially_refunded",
  "refunded_amount": "15000"
}

Best Practices

• Always verify payment status before refunding
• Use idempotency keys to avoid duplicate refunds
• Prefer refunds before disputes are filed
• Track cumulative refunded amounts
• Rely on webhooks for final state confirmation

Common Errors

Key Takeaways

Next Steps

• Verify Payment - Verify payment status
• Webhooks - Handle webhook events
• Responding to Disputes - Handle customer disputes