Capture, cancel, and refund payments
Capture, cancel, and refund payments
Use Admin payment operations to act on an existing provider reference. The action depends on the current payment state and gateway capabilities, not just the order’s business status.
Before you begin
Use an authorized Admin connection and your provider’s test configuration while implementing the workflow.
Read the current payment, intended and paid amounts, refunded amount, gateway, and pspReference.
Check canCapture or canRefund where applicable.
Use the Payment reference for the available fields.
1. Choose one action
| Action | Purpose |
|---|---|
| Capture | Capture an eligible payment amount |
| Cancel | Cancel a payment in a cancellable provider state |
| Refund | Return an eligible amount from captured funds |
A refund is not an order cancellation or inventory restock. Keep those operational decisions separate.
2. Submit the action
The capture input uses the gateway and provider reference, not a paymentId field:
Replace the amount with the eligible amount you intend to capture. Do not assume the example EUR amount is the current outstanding balance. For a refund, use:
Use no more than the currently refundable balance.
PaymentCancelInput uses gatewayId and pspReference without an amount.
Check typed errors before reporting success.
3. Handle an uncertain result
Disable duplicate submission while the request is pending. If the response is lost, read the current payment and order state before repeating the operation. The provider may have accepted the first action. Do not assume a generic idempotency header exists for all Thor mutations.
Verify
Confirm payment amounts, transactions, and the order’s paymentState after the action.
Test partial and full refunds separately.
Keep a safe correlation reference for support without logging provider secrets or raw payment details.
See Payments and transactions.