Refunds
A complete guide to processing full and partial refunds for TransactPay orders, understanding eligibility criteria, and handling mobile money disputes.
Refund Capabilities by Payment Channel
Ziba Pay allows merchants to reverse settled card and bank transfer orders directly through the REST API. Automated refunds are powered through TransactPay via POST/payment/zibapay/order/refund/:reference.
Mobile Money (MTN & Airtel) Reversals: Telecom mobile money networks do not currently offer an automated merchant-initiated refund API endpoint. To reverse or dispute a Mobile Money transaction, contact Ziba Pay Merchant Support with the transactionReferenceId for a manual carrier review.
| Channel | Refund Method | Partial Refunds | Settlement Window |
|---|---|---|---|
| Card Payments (TransactPay) | POST/payment/zibapay/order/refund/:reference | Supported (Amount <= unrefunded balance) | 3 to 7 business days to customer card account |
| Bank Transfers (TransactPay) | POST/payment/zibapay/order/refund/:reference | Supported (Amount <= original total) | 1 to 3 business days to customer bank account |
| MTN Mobile Money | Manual carrier dispute via Ziba Pay Support | Handled on case-by-case basis | Subject to telecom carrier dispute investigation |
| Airtel Money | Manual carrier dispute via Ziba Pay Support | Handled on case-by-case basis | Subject to telecom carrier dispute investigation |
Request Parameters & Schema
Refund requests require an authenticated merchant session bearer token. Note that the request body parameters use PascalCase (Reason and Amount) to match the backend controller specifications:
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
| reference | URL Path | string | Yes | The unique order reference assigned during order creation. |
Reason | JSON Body | string | Yes | Human-readable justification for the refund (e.g. 'Customer cancellation', 'Defective merchandise'). |
Amount | JSON Body | number | Yes | The monetary amount to refund. Must not exceed the remaining settled order amount. |
curl -X POST "https://payment-service-mh2d.onrender.com/api/payment/zibapay/order/refund/clxorderreference123" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <merchant_token>" \
-d '{
"Reason": "Customer requested full order cancellation",
"Amount": 1000
}'Preconditions & Eligibility Rules
Before issuing a refund, verify that your request satisfies the following platform rules:
- Order Status: The order must currently be in COMPLETED status. In-flight (PENDING) or previously FAILED orders cannot be refunded.
- Available Merchant Balance: The merchant account must have sufficient available balance to cover the refunded amount and any applicable provider fees.
- Maximum
Amount: TheAmountspecified cannot exceed the original captured order amount minus any prior partial refunds. - Session Authorization: Requests must carry an active merchant Authorization: Bearer <token>.
Error Handling & Response Codes
When executing refunds, anticipate and handle the following HTTP status outcomes:
| HTTP Code | Meaning | Common Cause | Remediation |
|---|---|---|---|
| 200 OK | Refund Accepted | Refund successfully recorded with upstream provider. | Update local database to REVERSED. |
| 400 Bad Request | Validation Error | Missing Reason, invalid Amount, or order is not COMPLETED. | Check payload fields and order state. |
| 401 Unauthorized | Authentication Failure | Bearer token missing or expired. | Refresh merchant session token. |
| 404 Not Found | Order Not Found | Order reference does not exist or belongs to another merchant. | Verify reference spelling. |
| 500 Internal Error | Upstream Failure | TransactPay bank network gateway error. | Retry after 30 seconds with exponential backoff. |