Refund
Process full or partial refunds on completed payments. Requires the refunds:write scope.
POST
/api/v1/{system}/refund🔒 refunds:writeRefund a previous payment the server executes against the acquirer (QR/wallet). Subject to a 60-second cooldown and amount validation (cannot exceed remaining balance). The cooldown applies to THIS server-driven endpoint only — it does NOT apply to card/device refunds recorded via saveTransaction, nor to LAN/Cloud refunds (which are device-executed); those are bound by the cumulative cap, not the cooldown.
Auth: Bearer JWT
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| referenceId | string | Yes | Original payment reference |
| refundAmount | string | Yes | Decimal string, 2 places, range 0.01–999999.99 (e.g. "5.00"); must be <= remaining balance. |
| refundReason | string | Yes | Reason for the refund |
| branchId | long | Yes | Branch user ID |
| configId | long | Yes | Terminal config ID |
⚠️ Live testing disabled for this endpoint — it modifies data. Use curl or the SDK against your sandbox.