> ## 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.

# Manual Inbound Confirmation

> Hold inbound SWIFT payments for operator review - complete or return them - while staying Universal Confirmations compliant.

This guide covers **inbound** payments - the ones you receive. In **manual mode** they are held for operator review before the beneficiary is credited - for institutions that must run sanctions, AML or KYC screening first. An interim confirmation is sent to the SWIFT network the moment the payment lands, so the **Universal Confirmations** deadline is always met while your operators take their time.

<Note>
  For **outbound** payments (the ones you send), see [Payment statuses](/payments/integration-guide/swift/track-payments).
</Note>

<Info>
  **Who needs manual mode?** Institutions that must screen inbound payments before releasing funds. If you credit on receipt, stay on [automatic confirmation](/payments/integration-guide/swift/auto-confirmation) (the default).
</Info>

## How it works

<Steps>
  <Step title="Payment received and held">
    The inbound payment lands as **Accepted** and is held with the reason `pending_review`. The beneficiary is **not** credited yet. You receive an **Accepted** webhook (`direction=INBOUND`).
  </Step>

  <Step title="Interim confirmation sent immediately">
    `ACSP/G002` - "accepted, credit pending internal review" - goes to the gpi Tracker at once, satisfying the confirmation deadline while the payment waits.
  </Step>

  <Step title="Operator review">
    Your operator reviews the payment in the PGW UI (or your system calls the review API) and chooses one of two actions.
  </Step>

  <Step title="Complete or Return">
    **Complete**: the payment is credited, moves to **Completed**, and the final `ACCC` confirmation is sent. **Return**: the funds go back to the sender - see the flow below.
  </Step>
</Steps>

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

  S->>N: Payment
  N->>P: Inbound payment
  P-->>C: Webhook (Accepted)
  P->>N: Confirmation ACSP/G002 (interim, payment held for review)
  alt Operator completes
    C->>P: COMPLETE
    P->>N: Confirmation ACCC (final)
    P-->>C: Webhook (Completed)
  else Operator returns
    C->>P: RETURN (reason code)
    P->>N: Return to sender (original UETR)
    P-->>C: Webhooks (Completed + Payment return lifecycle)
  end
```

### Cover payments (COVE)

Some correspondents settle in two parts: the customer payment (`pacs.008`) only announces the transfer, while the actual money moves separately as a bank-to-bank **cover transfer** (`pacs.009 COV`). The payment must not be credited until the cover arrives - and in manual mode, not before the operator approves it either.

<Steps>
  <Step title="Payment announced, funds not yet in">
    The inbound payment lands as **Accepted** and waits with the reason `awaiting_cover` (visible via [`GET /v3/payments/{id}`](/payments/api/accounts/get-payment), not in the webhook). An interim `ACSP/G004` confirmation ("awaiting cover") is sent to the Tracker immediately.
  </Step>

  <Step title="Cover arrives - payment enters the review queue">
    The matching `pacs.009 COV` is matched to the waiting payment automatically. The payment switches from `awaiting_cover` to `pending_review` (readable via [`GET /v3/payments/{id}`](/payments/api/accounts/get-payment)), an `ACSP/G002` confirmation is sent, and you receive an **Accepted** webhook.
  </Step>

  <Step title="Operator decides">
    From here the flow is the same as for any held payment: **Complete** (final `ACCC`, status Completed) or **Return** (funds go back as a Payment return).
  </Step>
</Steps>

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

  S->>N: Payment (settlement by cover)
  N->>P: Inbound payment
  P-->>C: Webhook (Accepted)
  P->>N: Confirmation ACSP/G004 (awaiting cover)
  S->>N: Cover transfer
  N->>P: Cover received
  P->>P: Match cover to the waiting payment
  P->>N: Confirmation ACSP/G002 (pending review)
  P-->>C: Webhook (Accepted)
  C->>P: Operator decides (Complete or Return)
```

## Returning a held payment

Instead of completing, the operator can **return** the payment to the sender - for example when a compliance review fails or the beneficiary account cannot be credited.

<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>

<Steps>
  <Step title="Operator selects Return">
    A return reason is picked (free-text note required when the reason is `NARR`).
  </Step>

  <Step title="Original is completed first">
    The original inbound transaction moves to **Completed** - it is never left in a rejected state.
  </Step>

  <Step title="Separate return transaction">
    A distinct **Payment return** transaction is created and linked to the original, sending the funds back under the original payment's **UETR**.
  </Step>

  <Step title="Tracked to completion">
    The return follows the standard outbound lifecycle (`Created → Sent to clear → Completed`, with `Accepted` in between when the statement confirms the debit first), tracked via the SWIFT Frontend API. Webhooks arrive with `type=Payment return`.
  </Step>
</Steps>

### 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                 |

A payment that was already **completed** can be returned too - see [Payment returns](/payments/integration-guide/swift/payment-returns).

## Webhooks

| Event                                          | `status`                                                 | `type`           |
| ---------------------------------------------- | -------------------------------------------------------- | ---------------- |
| Payment received (held)                        | `Accepted`                                               | `Payment`        |
| Operator **Complete**                          | `Completed`                                              | `Payment`        |
| Operator **Return** - original completes first | `Completed`                                              | `Payment`        |
| Return transaction lifecycle                   | `Created` → `Sent to clear` → (`Accepted`) → `Completed` | `Payment return` |

<Note>
  **The webhook does not carry the hold reason** - it only says `Accepted`. To distinguish a held payment (`pending_review`) or one awaiting cover (`awaiting_cover`) from a regular accepted payment, fetch the payment via [`GET /v3/payments/{id}`](/payments/api/accounts/get-payment) and read its **statusReason**, or check it in the PGW UI. The payment stays in `Accepted` until the operator acts; the next webhook (`Completed`) tells you the outcome.
</Note>

## Switching to manual mode

<Steps>
  <Step title="Request the change">
    Ask your Inventi integration or account manager to enable manual confirmation for your tenant. It is a single configuration flag.
  </Step>

  <Step title="Takes effect for new payments">
    The change applies to payments received after the flag is set; in-flight payments are unaffected.
  </Step>

  <Step title="Reversible">
    You can switch back to automatic at any time.
  </Step>
</Steps>

## API Reference

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

  <Card title="Get payment" icon="magnifying-glass" href="/payments/api/accounts/get-payment">
    `GET /v3/payments/{id}` - read the `statusReason` (`pending_review` / `awaiting_cover`)
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Automatic confirmation" icon="bolt" href="/payments/integration-guide/swift/auto-confirmation">
    The default mode - credit and confirm on receipt
  </Card>

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