Refund Guide
Zenith Payments supports refund requests through the Merchant API, together with API-based status checks on those requests.
This page explains how refunds work at a practical level. Use /openapi for the exact request and response schema details.
How refunds work
Refunds are requested against an existing payment.
Refund requests are manually approved by Zenith Payments. Because of that, creating a refund request does not mean the refund has already been completed. Your integration should treat refund creation and refund approval as separate steps.
Refunds can be:
- Base Amount — full payment amount before fees
- Partial Amount — a merchant-specified amount up to the base amount
Refund requests for the full amount including fees will generally not be approved. If that type of refund is required, contact Zenith Payments directly.
Create Refund Request
To initiate a refund request, make a POST request to:
/v2/payments/{paymentReference}/refundrequests
The refund request is tied to the paymentReference being refunded.
Refund value types
The refundValue field can be set as:
1— Base Amount2— Partial Amount
If there is any possibility of multiple refunds against the same paymentReference, provide a refundRequestUniqueId so that individual refund requests can be tracked safely.
See /openapi for the full request/response schema and example payloads.
Check Refund Request Status
To check the approval status of a refund request, make a GET request to:
/v2/payments/{paymentReference}/refundrequests
If there are multiple refund requests for the same payment, use the endpoint that includes the unique refund request identifier.
Your integration should treat refund status retrieval as the reliable way to confirm the current state of a refund request.
See /openapi for the full request/response schema and example payloads.
Practical guidance
When implementing refunds:
- keep the original
paymentReference - use a unique refund request identifier when multiple refunds are possible
- do not assume a created refund request is already approved
- reconcile refund state using the API instead of UI assumptions
- keep internal tracking aligned with the refund request lifecycle
Related pages
Summary
Refunds in the Merchant API are request-based and approval-driven.
Create the refund request through the API, track it using the payment reference and refund request identifier, and confirm status separately rather than assuming immediate completion.