How it works
1
Request arrives
The request is matched to your inbound payment automatically. A cancellation request is created and you are notified by webhook (
CANCELLATION_IN_PROGRESS) with the reason and the transaction ID.2
You decide
Review and respond via API or the PGW UI: accept (return the funds) or reject (keep them).
3
Accept: funds returned
The cancellation moves to
RETURNING and stays there while the return travels. The original inbound payment stays Completed; a separate Payment return transaction is created back to the originator and tracked via the SWIFT Frontend Tracker. When the return transaction reaches Completed (delivery confirmed), the cancellation gets its final status - webhook PAYMENT_RETURNED. The return itself answers the request.4
Reject: refusal sent
The cancellation moves to
REFUSING while your refusal travels back to the originating bank - webhook CANCELLATION_REFUSED on delivery (final). The funds stay with the beneficiary.Rejection reasons
A rejection carries one of these codes. The originating bank acts on it, so pick the one that says why the money is staying put.AC04 and AM04 are the everyday answers to “why can’t you return this money” - the beneficiary
account is closed, or the funds are no longer there. Reach for those before a generic refusal.
CUST and NOAS separate the two customer outcomes: asked and refused, asked and never answered.
PTNA (Passed To Next Agent) is not one of the choices. It describes an agent that has already
forwarded the payment onwards, which you never are when answering a request for a payment you
received. A cancellation request you send may still be refused with PTNA by a bank
further down the chain, and that answer reaches you unchanged.
ARDT takes no additionalInformation - the platform fills that field in for you. Send the
reason on its own:additionalInformation with ARDT returns 400 VALIDATION_ERROR. Every other code
takes it as optional free text, capped at 105 characters.Webhooks
Two webhook types are involved: the cancellation request emits Payment Cancellation Status Change events, while the Payment return transaction (created when you accept) emits Payment Status Change events.Status values are shown exactly as they arrive on the wire: the Payment Status Change webhook uses title case (
Cancelled, Sent to clear), the Cancellation Status Change webhook uses upper snake case (CANCELLATION_IN_PROGRESS, PAYMENT_RETURNED).API Reference
Respond to Cancellation Request
Accept and return the funds, or reject and keep them
Cancellation Status Webhook
Track the outcome
Respond to a SWIFT cancellation request through the v3 endpoint above. The v1 accept and reject
endpoints return
405 ILLEGAL_TRANSACTION_METHOD for SWIFT. Inbound SWIFT cancellation is
released per tenant - until yours is enabled, the endpoint returns 403 FEATURE_DISABLED.Next Steps
Payment statuses
Inbound statuses and hold reasons explained
Statements
Reconcile returned funds