> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finventi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Return Inbound SWIFT Payments

> Send received funds back to the sender - during manual review or after the payment has already been completed and credited.

Any payment you received can be returned to the sender. There are two entry points, depending on where the payment is:

* **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](/payments/integration-guide/swift/auto-confirmation).
* **Held for review** - manual mode only: the operator decides to return instead of completing during the review.

Either way the mechanics are the same: the original payment ends **Completed**, and the money goes back as a separate **Payment return** transaction.

## Which API to use

| Payment state                 | How it got there                                               | API to call                                                                 |
| ----------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `Completed`                   | Credited automatically (auto mode) or completed by an operator | [Returns API](/payments/api/swift/return-swift-payment)                     |
| `Accepted` (`pending_review`) | Held in the manual review queue                                | [Review API](/payments/api/swift/review-swift-payment) with action `RETURN` |

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.

<Note>
  When the **originating bank** asks for the money back (an incoming `camt.056`), you respond through a separate flow - see [Respond to cancellation requests](/payments/integration-guide/swift/inbound-cancellation).
</Note>

## Returning a completed payment

<Steps>
  <Step title="Return initiated">
    Via the PGW UI or the [returns API](/payments/api/swift/return-swift-payment), with a reason code (`NARR` requires a free-text note).
  </Step>

  <Step title="Original stays Completed">
    A separate **Payment return** transaction is created and linked to the original.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

```mermaid actions={true} theme={null}
sequenceDiagram
  autonumber
  participant C as Your System
  participant P as Payments Platform
  participant N as SWIFT Network
  participant S as Sending Bank

  C->>P: Return payment (reason code)
  P->>P: Create Payment return transaction (original stays Completed)
  P->>N: Return (original UETR)
  N->>S: Funds returned
  P-->>C: Webhooks (Payment return lifecycle)
  P->>N: Track return (SWIFT Frontend API)
  N-->>P: Return completed
  P-->>C: Webhook (Completed, 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](/payments/api/swift/review-swift-payment) with action `RETURN`. The original completes first, then the return follows the same lifecycle as above.

Full review flow: [Manual confirmation](/payments/integration-guide/swift/manual-confirmation).

## Return reasons

|                 |                                                                                     |
| --------------- | ----------------------------------------------------------------------------------- |
| Accepted codes  | `AC01` `AC04` `AC06` `AG01` `BE04` `BE08` `CUST` `DUPL` `FRAD` `MD07` `RR04` `NARR` |
| Additional info | **Mandatory when reason is `NARR`**, optional for all other reasons                 |

## Webhooks

| Event                                                                  | `status`                                                 | `type`           |
| ---------------------------------------------------------------------- | -------------------------------------------------------- | ---------------- |
| Original payment (already completed - no new event, stays `Completed`) | -                                                        | `Payment`        |
| Held payment completed on return (manual mode)                         | `Completed`                                              | `Payment`        |
| Return transaction lifecycle                                           | `Created` → `Sent to clear` → (`Accepted`) → `Completed` | `Payment return` |

<Note>
  `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`.
</Note>

## API Reference

<CardGroup cols={2}>
  <Card title="Return payment" icon="rotate-left" href="/payments/api/swift/return-swift-payment">
    `POST /v3/payments/{id}/returns` - return a completed payment
  </Card>

  <Card title="Review inbound payment" icon="user-check" href="/payments/api/swift/review-swift-payment">
    `POST /v3/payments/{id}/review-action` - RETURN a held payment
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Payment statuses" icon="route" href="/payments/integration-guide/swift/track-payments">
    Follow the return through its lifecycle
  </Card>

  <Card title="Statements" icon="file-lines" href="/payments/integration-guide/swift/statements">
    Reconcile returned funds
  </Card>
</CardGroup>