> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.
# Refunds & Chargebacks
> Initiate refunds on completed card transactions and manage chargeback disputes raised by customers through their card issuers.
## Overview
Payaza provides separate flows for two types of payment reversals:
* **Refunds** — merchant-initiated reversals of completed transactions. You initiate these when a customer requests a return or the order cannot be fulfilled.
* **Chargebacks** — customer-initiated disputes raised through their card issuer. Payaza notifies you and you can accept or reject the dispute through the API.
Refund and chargeback operations are irreversible and audit-critical. Restrict these actions to authorized roles in your system and maintain a complete log of every action taken.
***
## Key Requirements
Use your **public API key** encoded in Base64. See the [Authentication guide](/guides/authentication) for setup instructions.
Set these headers on every request:
```json theme={null}
{
"Authorization": "Payaza ",
"Content-Type": "application/json"
}
```
***
## Endpoints
### Refunds
| Method | Endpoint | Description |
| ------ | ------------------------------------------------------- | ----------------------------------------------------- |
| `POST` | `/refund-chargeback/refund/merchant/api/refund` | Initiate a refund on a completed transaction |
| `GET` | `/refund-chargeback/refund/merchant/api/refund_history` | List refund history with optional date/status filters |
### Chargebacks
| Method | Endpoint | Description |
| ------ | --------------------------------------------------------------------------- | ------------------------------------------ |
| `GET` | `/refund-chargeback/chargeback/merchant/api/chargeback_requests` | List open and resolved chargeback requests |
| `POST` | `/refund-chargeback/chargeback/merchant/api/accept_reject_chargeback` | Accept or reject a chargeback dispute |
| `GET` | `/refund-chargeback/chargeback/merchant/api/chargeback_transaction_history` | Full transaction-level chargeback history |
***
## Refund flow
Retrieve the `transaction_reference` of the completed transaction you want to refund. Verify the transaction status is `"Completed"` before initiating a refund.
Call the Refund endpoint with the `transaction_reference` and the amount to refund. Partial refunds are supported — the `refund_amount` must not exceed the original transaction amount.
Check the refund status from the response or use the Refund History endpoint to verify the refund was processed successfully.
### Initiate a refund
```bash cURL — Full refund theme={null}
curl --request POST \
--url https://api.payaza.africa/live/refund-chargeback/refund/merchant/api/refund \
--header 'Authorization: Payaza ' \
--header 'Content-Type: application/json' \
--data '{
"transaction_reference": "TXN20240501A",
"refund_amount": 24.00,
"refund_reason": "Customer request"
}'
```
```bash cURL — Partial refund theme={null}
curl --request POST \
--url https://api.payaza.africa/live/refund-chargeback/refund/merchant/api/refund \
--header 'Authorization: Payaza ' \
--header 'Content-Type: application/json' \
--data '{
"transaction_reference": "TXN20240501A",
"refund_amount": 10.00,
"refund_reason": "Partial cancellation"
}'
```
**Sample response**
```json theme={null}
{
"message": "Operation Completed",
"data": {
"message": "Refund Processed Successfully",
"refund_transaction_reference": "RF20240402-Z81IZX5OPCG1NGN",
"payment_transaction_reference": "TXN20240501A",
"status": "SUCCESS",
"original_transaction_amount": 24.00,
"refunded_amount": 24.00,
"successful": true,
"rrn": "615098123313"
}
}
```
Save the `refund_transaction_reference` from the response — it is the only identifier you can use to check refund status later.
### List refund history
```bash cURL theme={null}
curl --request GET \
--url 'https://api.payaza.africa/live/refund-chargeback/refund/merchant/api/refund_history?page=1&size=10&refund_status=SUCCESS' \
--header 'Authorization: Payaza '
```
**Query parameters**
| Parameter | Required | Description |
| --------------- | -------- | ------------------------------------------- |
| `page` | Yes | Page number (starts at `1`) |
| `size` | Yes | Records per page |
| `refund_status` | Yes | Filter by status: `SUCCESS`, `Initialized` |
| `from` | No | Start date — format `YYYY-MM-DD` |
| `to` | No | End date — format `YYYY-MM-DD` |
| `currency` | No | Filter by currency code (e.g. `NGN`, `USD`) |
***
## Chargeback flow
Payaza notifies you of a new chargeback via a webhook, or you can poll the List Chargeback Requests endpoint to check for open disputes.
Examine the transaction details, order records, and any evidence that the transaction was legitimate and authorized by the cardholder.
Call the Accept/Reject endpoint with your decision. Responding promptly improves the likelihood of a favorable resolution — card networks impose time limits for merchant responses.
### List chargeback requests
Retrieve all open and resolved chargeback requests for your account.
```bash cURL theme={null}
curl --request GET \
--url 'https://api.payaza.africa/live/refund-chargeback/chargeback/merchant/api/chargeback_requests?page=1&size=10' \
--header 'Authorization: Payaza '
```
**Sample response**
```json theme={null}
{
"message": "Chargeback requests fetched successfully",
"status": true,
"data": {
"content": [
{
"chargeback_reference": "CB20240601-XY8ZPQ",
"transaction_reference": "TXN20240501A",
"transaction_amount": 24.00,
"currency": "NGN",
"chargeback_reason": "Customer claims non-receipt of goods",
"chargeback_status": "PENDING",
"raised_date": "2024-06-01T08:15:00.000Z",
"response_deadline": "2024-06-08T08:15:00.000Z"
}
],
"total": 1,
"page": 1,
"size": 10
}
}
```
### Accept or reject a chargeback
Respond to a chargeback with your decision. Use `"ACCEPT"` to concede the dispute and allow the reversal, or `"REJECT"` to contest it with a reason.
```bash cURL theme={null}
curl --request POST \
--url https://api.payaza.africa/live/refund-chargeback/chargeback/merchant/api/accept_reject_chargeback \
--header 'Authorization: Payaza ' \
--header 'Content-Type: application/json' \
--data '{
"chargeback_reference": "CB20240601-XY8ZPQ",
"decision": "REJECT",
"reason": "Transaction was authorized by the cardholder. Proof of delivery attached."
}'
```
**Request parameters**
| Parameter | Type | Required | Description |
| ---------------------- | -------- | -------- | ------------------------------------------------------------------- |
| `chargeback_reference` | `string` | Yes | The chargeback reference from the List Chargeback Requests response |
| `decision` | `string` | Yes | Your response — `"ACCEPT"` or `"REJECT"` |
| `reason` | `string` | Yes | Explanation supporting your decision |
**Sample response**
```json theme={null}
{
"message": "Chargeback response submitted successfully",
"status": true,
"data": {
"chargeback_reference": "CB20240601-XY8ZPQ",
"decision": "REJECT",
"submission_date": "2024-06-03T10:22:00.000Z",
"chargeback_status": "MERCHANT_RESPONDED"
}
}
```
### Chargeback transaction history
Retrieve a full transaction-level history of all chargeback activity on your account.
```bash cURL theme={null}
curl --request GET \
--url 'https://api.payaza.africa/live/refund-chargeback/chargeback/merchant/api/chargeback_transaction_history?page=1&size=10' \
--header 'Authorization: Payaza '
```
**Sample response**
```json theme={null}
{
"message": "Chargeback history fetched successfully",
"status": true,
"data": {
"content": [
{
"chargeback_reference": "CB20240601-XY8ZPQ",
"transaction_reference": "TXN20240501A",
"transaction_amount": 24.00,
"currency": "NGN",
"chargeback_reason": "Customer claims non-receipt of goods",
"merchant_decision": "REJECT",
"final_status": "RESOLVED_IN_FAVOR_OF_MERCHANT",
"raised_date": "2024-06-01T08:15:00.000Z",
"resolved_date": "2024-06-10T14:00:00.000Z"
}
],
"total": 1,
"page": 1,
"size": 10
}
}
```
***
## Best practices
* **Restrict access** — Only authorized roles (e.g. finance ops, not frontline support) should be able to initiate refunds or respond to chargebacks
* **Keep an audit trail** — Log every refund initiation and chargeback response, including who triggered it and when
* **Align with customer support tools** — Connect refund and chargeback statuses to your CRM or ticketing system so support agents have real-time visibility
* **Respond to chargebacks promptly** — Card networks impose time limits for merchant responses; missing the window typically results in an automatic loss
***
## What's next
Understand the original card charge flow before handling reversals.
Void a pre-authorization before capture to avoid the need for a refund.