Capture, cancel, and refund payments

Outcome: an operator performs one supported payment action and verifies both payment and order state after the provider responds.

Prerequisites

Use an Admin credential, order and payment IDs, the payment’s PSP reference, and configured provider test credentials. These steps are schema- and source-validated; run them only in an authorized test environment before using a live gateway.

1. Inspect current state

Query the order’s paymentState and payments. For each payment, request intended, paid, and refunded amounts, gateway canCapture and canRefund, PSP reference, and transactions. Select an action from current state and capability, not from the UI’s last cached state.

2. Perform one action

GraphQL

Code in graphql

Use PaymentCaptureInput exactly. Use paymentCancel only for a cancellable provider state. Use paymentRefund only for captured funds and do not request more than the refundable balance. Provider and insufficient-balance failures are typed results, not reasons for an unchanged automatic retry loop.

3. Recover from uncertainty

If the network response is lost, query the payment by its stable identifiers and the order’s current state before repeating the action. The provider may have accepted the first request. Preserve the PSP reference in operational logs without logging provider secrets or payment data.

4. Verify

Re-read payment amounts, transactions, and order paymentState. A partial refund and full refund produce different states. See Payments and transactions.