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

# Send SWIFT Payments

> Create and send international wire transfers via SWIFT.

Send international wire transfers to any bank worldwide via SWIFT. The platform handles message routing, correspondent banking and status tracking - you integrate one API and consume webhooks.

## How a payment flows

You create the payment, the platform routes it through the SWIFT network to the correspondent bank, and every status change comes back to you as a webhook. The final outcome is confirmed by tracking the payment via the SWIFT Frontend API.

Whether a payment needs approval before it goes out depends on the **transaction signing** setting of your tenant (see [Before you send](#before-you-send)).

<Tabs>
  <Tab title="Without signing (default)">
    ```mermaid actions={true} theme={null}
    sequenceDiagram
      autonumber
      participant C as Your System
      participant P as Payments Platform
      participant N as SWIFT Network
      participant B as Correspondent Bank

      C->>P: Create SWIFT payment
      P-->>C: Webhook (Created)
      P->>N: Payment message
      N-->>P: Message accepted
      N->>B: Route to correspondent
      P-->>C: Webhook (Sent to clear)
      P-->>C: Webhook (Accepted) - debit confirmed on statement
      P->>N: Track delivery (SWIFT Frontend API)
      N-->>P: Delivery confirmed
      P-->>C: Webhook (Completed)
    ```

    `Created → Sent to clear → Accepted → Completed`
  </Tab>

  <Tab title="With signing">
    ```mermaid actions={true} theme={null}
    sequenceDiagram
      autonumber
      participant C as Your System
      participant P as Payments Platform
      participant N as SWIFT Network
      participant B as Correspondent Bank

      C->>P: Create SWIFT payment
      P-->>C: Webhook (Created)
      P-->>C: Webhook (To sign)
      C->>P: Sign / approve
      P-->>C: Webhook (Signed)
      P->>N: Payment message
      N-->>P: Message accepted
      N->>B: Route to correspondent
      P-->>C: Webhook (Sent to clear)
      P-->>C: Webhook (Accepted) - debit confirmed on statement
      P->>N: Track delivery (SWIFT Frontend API)
      N-->>P: Delivery confirmed
      P-->>C: Webhook (Completed)
    ```

    `Created → To sign → Signed → Sent to clear → Accepted → Completed`
  </Tab>

  <Tab title="Rejected">
    ```mermaid actions={true} theme={null}
    sequenceDiagram
      autonumber
      participant C as Your System
      participant P as Payments Platform
      participant N as SWIFT Network

      C->>P: Create SWIFT payment
      P-->>C: Webhook (Created)
      P->>N: Payment message
      N-->>P: Message accepted
      P-->>C: Webhook (Sent to clear)
      N-->>P: Rejection (validation / compliance / correspondent)
      P-->>C: Webhook (Rejected)
    ```

    `Created → Sent to clear → Rejected`

    Common reasons: invalid or unknown BIC, insufficient funds, sanctions or compliance screening hit, message formatting errors, regulatory restrictions.
  </Tab>

  <Tab title="Returned">
    ```mermaid actions={true} theme={null}
    sequenceDiagram
      autonumber
      participant C as Your System
      participant P as Payments Platform
      participant N as SWIFT Network
      participant B as Correspondent Bank

      C->>P: Create SWIFT payment
      P->>N: Payment message
      N->>B: Route to correspondent
      P-->>C: Webhook (Sent to clear)
      B->>N: Return of funds
      N->>P: Return (carries original UETR)
      P->>P: Match original payment by UETR
      P-->>C: Webhook (Completed, type=Payment)
      P->>P: Create credit transaction
      P-->>C: Webhook (Completed, type=Payment return)
    ```

    Original: `Created → Sent to clear → Completed`
    Return: separate **credit** transaction, created directly as `Completed` (`type=Payment return`)

    <Info>
      A return never moves your original payment to `Rejected` - the original ends `Completed`, and the returned money arrives as a distinct **Payment return** transaction, so both stay visible and reconcilable.
    </Info>
  </Tab>
</Tabs>

<Note>
  Full status lifecycle, error flows and webhook reference: [Payment statuses](/payments/integration-guide/swift/track-payments).
</Note>

## Before you send

<AccordionGroup>
  <Accordion title="Check the beneficiary bank" icon="building-columns">
    One call covers it all - [Bank Information API](/payments/api/accounts/get-bank-information-for-iban) (`GET /v1/bank-info/{iban}`) returns the bank's **BIC**, **name** and a per-scheme **reachability map** including `SWIFTCORE`:

    ```json theme={null}
    {
      "bic": "WESTGB2LXXX",
      "bankName": "Western Bank",
      "sepaSchemas": { "SEPAINST": false, "SEPACT": false, "SDDCORE": false, "SWIFTCORE": true }
    }
    ```

    Use it to validate the IBAN and confirm the beneficiary bank is a reachable SWIFT participant (`SWIFTCORE: true`). The same check also runs automatically during payment processing - a payment to an unreachable bank is rejected with a clear validation error instead of being sent.
  </Accordion>

  <Accordion title="Beneficiary bank BIC is resolved for you" icon="wand-magic-sparkles">
    You do not need to supply the beneficiary bank's BIC - when the creditor account is an IBAN, the platform resolves the BIC from it automatically. Provide `creditor.agentBic` only when the account is not an IBAN.
  </Accordion>

  <Accordion title="Use idempotency" icon="key">
    Always send an `Idempotency-Key` header when creating payments to prevent duplicates during retries.

    <Warning>
      Without idempotency, network retries can result in duplicate transfers.
    </Warning>
  </Accordion>

  <Accordion title="Transaction signing (optional)" icon="signature">
    Signing is a per-tenant setting - it can be **enabled or disabled** for your account.

    **Signing disabled** (default): no approval step is needed - the payment goes straight out.

    `Created → Sent to clear → ...`

    **Signing enabled**: every payment must be approved before it is sent. It waits in **To sign** until approved via the [sign](/payments/api/swift/transactions-sign), [approve](/payments/api/swift/transaction-approve) or [decline](/payments/api/swift/transaction-decline) APIs (or the PGW UI). Declining cancels the payment.

    `Created → To sign → Signed → Sent to clear → ...`
  </Accordion>
</AccordionGroup>

## Create a payment

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pgw-sandbox.finventi.com/v2/transactions/swift \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: {uuid}" \
    -d '{
      "amount": 100000,
      "currency": "EUR",
      "priority": "NORM",
      "debtor": {
        "name": "Sender Ltd",
        "iban": "LT543210010000000003",
        "address": { "streetName": "Upes g.", "buildingNumber": "5", "postCode": "08303", "townName": "Vilnius", "country": "LT" }
      },
      "creditor": {
        "name": "Recipient Ltd",
        "iban": "GB82WEST12345698765432",
        "address": { "streetName": "High Street", "buildingNumber": "12", "postCode": "SW1A 1AA", "townName": "London", "country": "GB" }
      },
      "settlement": {
        "method": "INDA",
        "date": "2026-08-05",
        "iban": "LT111000011101001000"
      },
      "charges": { "bearer": "SHAR" },
      "remittance": "Invoice INV-2026-001"
    }'
  ```

  ```json Response theme={null}
  {
    "result": {
      "id": 12345,
      "status": "Created"
    }
  }
  ```
</CodeGroup>

The full request and response schema - all fields, validation rules and examples - is in the [API reference](#api-reference) below.

### Charge bearer

SWIFT transfers may incur correspondent bank charges. Choose who pays via `charges.bearer`:

<CardGroup cols={3}>
  <Card title="DEBT" icon="hand-holding-dollar">
    **You pay all charges**

    Beneficiary receives the full amount
  </Card>

  <Card title="SHAR" icon="handshake">
    **Shared charges** (default)

    Each party pays their bank's fees
  </Card>

  <Card title="CRED" icon="user-minus">
    **Beneficiary pays**

    Charges deducted from the amount
  </Card>
</CardGroup>

## Integration Checklist

<Steps>
  <Step title="Implement idempotency">
    Generate and persist `Idempotency-Key` for each payment
  </Step>

  <Step title="Check beneficiary bank reachability">
    Use the Bank Information API to confirm the beneficiary bank is a reachable SWIFT participant
  </Step>

  <Step title="Handle multi-currency">
    Specify source and target currencies correctly
  </Step>

  <Step title="Implement webhook receiver">
    Track payment status via webhooks
  </Step>
</Steps>

## API Reference

<CardGroup cols={2}>
  <Card title="Create SWIFT payment" icon="paper-plane" href="/payments/api/swift/create-swift-payment">
    `POST /v2/transactions/swift` - complete field documentation
  </Card>

  <Card title="Bank information" icon="building-columns" href="/payments/api/accounts/get-bank-information-for-iban">
    `GET /v1/bank-info/{iban}` - BIC and SWIFT reachability check
  </Card>

  <Card title="Sign transactions" icon="signature" href="/payments/api/swift/transactions-sign">
    `POST /v1/transactions/signatures` - sign payments waiting in To sign
  </Card>

  <Card title="Approve / decline" icon="check" href="/payments/api/swift/transaction-approve">
    `PATCH /v1/transactions/{id}:approve` and [`:decline`](/payments/api/swift/transaction-decline)
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Payment statuses" icon="route" href="/payments/integration-guide/swift/track-payments">
    What happens after you send - every status explained
  </Card>

  <Card title="Cancel SWIFT payments" icon="ban" href="/payments/integration-guide/swift/cancellation">
    Stop a payment that should not go through
  </Card>
</CardGroup>