Refunds & Chargebacks

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 for setup instructions.

Set these headers on every request:

{
  "Authorization": "Payaza <base64-encoded-public-key>",
  "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

Identify the transaction

Retrieve the transaction_reference of the completed transaction you want to refund. Verify the transaction status is "Completed" before initiating a refund.

Submit the 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.

Confirm the outcome

Check the refund status from the response or use the Refund History endpoint to verify the refund was processed successfully.

Initiate a refund

curl --request POST \
  --url https://api.payaza.africa/live/refund-chargeback/refund/merchant/api/refund \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_reference": "TXN20240501A",
    "refund_amount": 24.00,
    "refund_reason": "Customer request"
  }'

curl --request POST \
  --url https://api.payaza.africa/live/refund-chargeback/refund/merchant/api/refund \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_reference": "TXN20240501A",
    "refund_amount": 10.00,
    "refund_reason": "Partial cancellation"
  }'

Sample response

{
  "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

cURL

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 <Your public API key encoded in base 64>'

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

Receive the chargeback notification

Payaza notifies you of a new chargeback via a webhook, or you can poll the List Chargeback Requests endpoint to check for open disputes.

Review the dispute

Examine the transaction details, order records, and any evidence that the transaction was legitimate and authorized by the cardholder.

Accept or reject the chargeback

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.

cURL

curl --request GET \
  --url 'https://api.payaza.africa/live/refund-chargeback/chargeback/merchant/api/chargeback_requests?page=1&size=10' \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>'

Sample response

{
  "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.

cURL

curl --request POST \
  --url https://api.payaza.africa/live/refund-chargeback/chargeback/merchant/api/accept_reject_chargeback \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>' \
  --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

{
  "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.

cURL

curl --request GET \
  --url 'https://api.payaza.africa/live/refund-chargeback/chargeback/merchant/api/chargeback_transaction_history?page=1&size=10' \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>'

Sample response

{
  "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

Get started

Developer tools

Accept payments

Send money

Disputes & refunds

Account management

Split Settlements

Overview

Key Requirements

Endpoints

Refunds

Chargebacks

Refund flow

Initiate a refund

List refund history

Chargeback flow

List chargeback requests

Accept or reject a chargeback

Chargeback transaction history

Best practices

What’s next

Card Collections

Auth, Capture & Void

​Overview

​Key Requirements

​Endpoints

​Refunds

​Chargebacks

​Refund flow

​Initiate a refund

​List refund history

​Chargeback flow

​List chargeback requests

​Accept or reject a chargeback

​Chargeback transaction history

​Best practices

​What’s next

Card Collections

Auth, Capture & Void

Overview

Key Requirements

Endpoints

Refunds

Chargebacks

Refund flow

Initiate a refund

List refund history

Chargeback flow

List chargeback requests

Accept or reject a chargeback

Chargeback transaction history

Best practices

What’s next