Refund part or all of a settled payment that belongs to the authenticated merchant.
Send the bearer token from POST /api/public/authorization. Do not send the raw API key.
Generate a new Idempotency-Key for each refund attempt, for example a UUID.
Sending the same key again for this payment returns the original refund and does not pay the customer again, even if amount is different.
A second partial refund needs a new key. Using the same key on a different payment returns 409.
A failed refund stays tied to that key. To try again, send a new key.
The payment must already be settled. acsc with settled: false is not refundable yet.
The payer must still have a saved BSB or PayID. Inbound PayID, destination, bookkeeper, settlement, and redeem rows are refused.
Developer credits are checked only outside production, and only for a developer merchant when credit limits are configured.
One credit is taken after a new Ok or Pending result. A replay and a Failed result do not take a credit.
Error Codes
| Code | Status | Reason | What to do |
|---|---|---|---|
| GN-0000 | 422 | Idempotency-Key is missing | Send a client-generated key, such as a UUID. |
| GN-0000 | 404 | Payment initiation not found for this merchant | Use a payment_initiation_id owned by the token's merchant. |
| PI-0003 | 422 | Amount is zero or negative | Send a positive dollar amount. |
| PI-0002 | 422 | Payment cannot be refunded, or the amount is above the remainder | Confirm the payment is settled, has no destination, and the payer still has an account. Lower the amount to the remainder. |
| GN-0000 | 422 | Already refunded | The full payment amount is already reserved by Ok and Pending refunds. |
| GN-0000 | 422 | Refund wallet not found | The merchant ledger wallet is missing. |
| GN-0000 | 422 | Not enough balance to refund | Retry later. The platform balance does not cover this amount. |
| GN-0000 | 409 | This key was already used for a different payment | Send a new Idempotency-Key. |
| GN-0000 | 402 | Developer credits exhausted | Non-production only. Top up credits and retry with the same key only if no refund row was created. |
| Provider code | 422 | The scheme rejected the refund | Read message and error_code. Retry only with a new Idempotency-Key. |
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||