Errors and Troubleshooting

Most refund errors return HTTP 422 with errorCode: invalidRefundRequest. Read the message field to tell them apart.

Refund errors

HTTP	`errorCode`	`message`	Cause	What to do
422	`invalidRefundRequest`	Refund currency must match original transaction	`currencyCode` differs from the original	Send the original transaction's currency
422	`invalidRefundRequest`	Only PRE_AUTHORISATION_COMPLETION, PURCHASE, MOTO or CASH_ADVANCE can be refunded	The transaction type cannot be refunded	Not refundable through this API
422	`invalidRefundRequest`	Only posted or settled POS transactions can be refunded	The transaction has not settled yet	Wait until it has settled, then retry. To reverse a payment on the day it was made, void it at the terminal.
422	`invalidRefundRequest`	Authority refunds proposition service must be disabled for this merchant	The authority refunds service is on	The merchant must ask Network International to switch it off
401	`accessDenied`	Requested refund exceeds available refundable amount	Amount is more than what is left to refund	Lower the amount; check for earlier partial refunds
404	`invalidRefundRequest`	Invalid refund request amount	The amount is missing or invalid	Send `amount.value` as a positive integer in minor units
200	none	`status: DECLINED`	The refund was declined	See the note below

⚠️
Two errors have misleading messages
A refund above the refundable balance returns 401, and its localizedMessage reads "You do not have sufficient permissions". A missing amount returns 404 Not Found. Handle these by message, not by HTTP code alone.

Access and request errors

HTTP	Cause	What to do
401	Access token missing, wrong or expired	Request a new token and retry
403	The API key is not linked to this merchant	Check the key belongs to the merchant in the path
404	The merchant ID or transaction ID does not exist	Check both IDs; search again to confirm the transaction ID
400	Malformed JSON or wrong content type	Validate the body and headers
422	Search date range invalid: `invalidData`	`endDate` on or after `startDate`, within 31 days

Common problems

Problem	Likely cause	What to do
The search returns nothing	Wrong approval code, or the date range misses the payment	Check the code against the receipt; widen the dates within 31 days
The search returns several transactions	Approval codes are not unique	Filter by merchant ID, terminal ID, card last four digits or RRN
Every refund fails with the authority refunds error	The merchant uses deferred refund approval	Contact your relationship manager

For the eligibility rules in full, see Refund POS transactions through the API.