Refund approval
Initiate refunds as an operator, and approve refunds that exceed the app's threshold.
Operators can initiate refunds from the dashboard and approve ones that exceed an app's configured threshold. This complements the app-API refunds described in the Refunds guide.
Search refunds
GET /admin/refunds (requires refund:read) is a cross-app, paginated refund
search. Filter by applicationId, mode, status, paymentId, and a from/to
date window. Results are narrowed to the apps your grants cover.
Initiate a refund
POST /admin/payments/{id}/refunds (requires refund:create) refunds a settled
payment. The amount is in minor units and is bounded by the
refundable balance.
- If the amount is within the app's
refundApprovalThresholdMinor, the refund goes straight toPENDING. - If it exceeds the threshold, it is parked in
AWAITING_APPROVALand emits no webhook until approved.
Approve an above-threshold refund
POST /admin/refunds/{id}/approve (requires refund:approve) releases a parked
refund to the gateway, stamping the approver. The refund moves to PENDING and the
normal async outcome (refund.succeeded / refund.failed) follows.
Approval is a sensitive action: it requires step-up re-auth and is
written to the audit log with the approver's identity. Separating
refund:create from refund:approve enforces four-eyes control on large
refunds.
Retrying a failed refund
A FAILED refund freed its reserved balance, so it can be retried safely by
initiating again for the same amount — the over-refund guard guarantees it can't
compound. Retry is also gated by refund:create.