- Already completed - the payment was credited (automatically or by an operator) and needs to be returned later: a beneficiary’s request, a compliance issue that surfaced after crediting. Works in both confirmation modes, including after automatic confirmation.
- Held for review - manual mode only: the operator decides to return instead of completing during the review.
Which API to use
Calling the wrong one fails: the review API only works on a payment that is still held, the returns API only on a completed one.
When the originating bank asks for the money back (an incoming
camt.056), you respond through a separate flow - see Respond to cancellation requests.Returning a completed payment
1
Return initiated
Via the PGW UI or the returns API, with a reason code (
NARR requires a free-text note).2
Original stays Completed
A separate Payment return transaction is created and linked to the original.
3
Tracked to completion
The return is sent back to the originator under the original payment’s UETR and tracked to completion via the SWIFT Frontend API. Webhooks arrive with
type=Payment return.Returning a held payment (manual mode)
While a payment waits in the review queue (Accepted, reason pending_review), the operator can return it instead of completing - via the PGW UI or the review API with action RETURN. The original completes first, then the return follows the same lifecycle as above.
Full review flow: Manual confirmation.
Return reasons
Webhooks
Accepted is not guaranteed: it appears only when the debit is confirmed on the correspondent account statement before delivery is confirmed. If the SWIFT Frontend API confirms delivery first, the transaction goes from Sent to clear straight to Completed.API Reference
Return payment
POST /v3/payments/{id}/returns - return a completed paymentReview inbound payment
POST /v3/payments/{id}/review-action - RETURN a held paymentNext Steps
Payment statuses
Follow the return through its lifecycle
Statements
Reconcile returned funds