Skip to main content

​
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

MethodEndpointDescription
POST/refund-chargeback/refund/merchant/api/refundInitiate a refund on a completed transaction
GET/refund-chargeback/refund/merchant/api/refund_historyList refund history with optional date/status filters

​
Chargebacks

MethodEndpointDescription
GET/refund-chargeback/chargeback/merchant/api/chargeback_requestsList open and resolved chargeback requests
POST/refund-chargeback/chargeback/merchant/api/accept_reject_chargebackAccept or reject a chargeback dispute
GET/refund-chargeback/chargeback/merchant/api/chargeback_transaction_historyFull transaction-level chargeback history

​
Refund flow

1

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.
2

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.
3

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"
  }'
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
ParameterRequiredDescription
pageYesPage number (starts at 1)
sizeYesRecords per page
refund_statusYesFilter by status: SUCCESS, Initialized
fromNoStart date — format YYYY-MM-DD
toNoEnd date — format YYYY-MM-DD
currencyNoFilter by currency code (e.g. NGN, USD)

​
Chargeback flow

1

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.
2

Review the dispute

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

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
ParameterTypeRequiredDescription
chargeback_referencestringYesThe chargeback reference from the List Chargeback Requests response
decisionstringYesYour response — "ACCEPT" or "REJECT"
reasonstringYesExplanation 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

​
What’s next

Card Collections

Understand the original card charge flow before handling reversals.

Auth, Capture & Void

Void a pre-authorization before capture to avoid the need for a refund.