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

> ## Agent Instructions
> Treat the published Augustus OpenAPI specification (https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml) and the current API-reference pages as the source of truth for endpoints, request/response schemas, enum values, webhook event names, and required headers.
> Prefer the 2026-05-01 Banking API and @augustusbank/typescript-sdk for all new integrations. The 2023-01-01 API is a separate, older surface covering two products — Open Banking (instant bank transfer) checkout and refunds, and Manual Bank Transfer (MBT); use it only when one of those products is specifically required.
> Cite or link the relevant docs.augustus.com page when answering integration questions.
> Do not infer support for currencies, networks, scopes, account types, or operations that are not present in the current documentation.
> Use the sandbox base URL (https://api.sandbox.augustus.com) and placeholder credentials in examples. Never include or request a real API key.
> The Augustus docs MCP server (https://docs.augustus.com/mcp) provides documentation search and retrieval only; it does not execute authenticated Augustus API actions.

# Payouts

> Send money anywhere: customers, partners, suppliers, or external accounts.

Send funds from an Augustus account to any external bank account or linked wallet via API or via the Dashboard.

## Supported currencies

* **Fiat:** EUR, GBP, USD.
* **Stablecoins:** USDC (Ethereum, Solana, Polygon).

## Create a payout

<Tabs>
  <Tab title="2026-05-01">
    <CodeGroup>
      ```ts USD theme={null}
      import Augustus from '@augustusbank/typescript-sdk'

      const client = new Augustus()
      const payout = await client.payouts.create({
        account_id: 'your-usd-account-id',
        amount: '2500.00',
        currency: 'USD',
        rail: 'fedwire',
        unstructured_remittance_information: 'Invoice 1234',
        counterparty: {
          financial_address: {
            type: 'aba',
            routing_number: '021000021',
            account_number: '123456789',
            account_holder_name: 'Acme Trading LLC',
          },
        },
      })
      ```

      ```ts EUR theme={null}
      import Augustus from '@augustusbank/typescript-sdk'

      const client = new Augustus()
      const payout = await client.payouts.create({
        account_id: 'your-eur-account-id',
        amount: '100.00',
        currency: 'EUR',
        unstructured_remittance_information: 'Invoice 1234',
        counterparty: {
          financial_address: {
            type: 'iban',
            iban: 'DE93500105176719451585',
            account_holder_name: 'Chris Simon',
          },
        },
      })
      ```

      ```ts GBP theme={null}
      import Augustus from '@augustusbank/typescript-sdk'

      const client = new Augustus()
      const payout = await client.payouts.create({
        account_id: 'your-gbp-account-id',
        amount: '100.00',
        currency: 'GBP',
        unstructured_remittance_information: 'Invoice 1234',
        counterparty: {
          financial_address: {
            type: 'sort_code',
            sort_code: '040004',
            account_number: '12345678',
            account_holder_name: 'Chris Simon',
          },
        },
      })
      ```

      ```ts USDC theme={null}
      import Augustus from '@augustusbank/typescript-sdk'

      const client = new Augustus()
      const payout = await client.payouts.create({
        account_id: 'your-usdc-wallet-id',
        amount: '1000.00',
        currency: 'USDC',
        counterparty: {
          financial_address: {
            type: 'crypto_wallet',
            address: 'your-linked-wallet-address',
            blockchain: 'ethereum',
          },
        },
      })
      ```
    </CodeGroup>

    <Note>
      Find each Account ID in the Dashboard under [Accounts → Details](https://dashboard.augustus.com/dashboard/accounts).
    </Note>

    [**POST** `/v1/payouts` in the API Reference →](/api-reference/payouts/create-payout)
  </Tab>

  <Tab title="2023-01-01">
    ```ts theme={null}
    import Ivy from '@getivy/node-sdk'

    const client = new Ivy()
    const payout = await client.payouts.create({
      amount: 100,
      currency: 'EUR',
      destination: {
        type: 'beneficiary',
        financialAddress: {
          type: 'iban',
          iban: {
            iban: 'DE93500105176719451585',
            accountHolderName: 'Chris Simon',
          },
        },
      },
    })
    ```

    [**POST** `/api/service/payout` in the API Reference →](/api-reference/payout/create-a-payout)
  </Tab>
</Tabs>

### Key fields

| Field                                 | Behavior                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currency`                            | `EUR`, `GBP`, `USD`, or `USDC`.                                                                                                                                                                                                                                                                                                                                 |
| `rail`                                | Required for USD: `"ach"` or `"fedwire"` for domestic payments, `"swift"` for international. Optional for EUR (`"sepa_instant"`, `"sepa"`) and GBP (`"faster_payments"`). The payout resource records the rail the payment traveled on.                                                                                                                         |
| `counterparty`                        | Who receives the money: exactly one of a saved `counterparty_id` or an inline `counterparty` object, which creates the counterparty automatically. Its `financial_address` follows the currency: `iban` for EUR, `sort_code` for GBP, `aba` for domestic USD, `swift` for international USD, a [linked wallet](/docs/accounts/wallets#linked-wallets) for USDC. |
| `unstructured_remittance_information` | Free text shown to the receiver (max 140 characters); it appears on the counterparty's bank statement, and each rail page states how it arrives. Not supported on blockchain rails.                                                                                                                                                                             |
| `metadata`                            | Key-value pairs of your own data, returned on every payout response and webhook payload.                                                                                                                                                                                                                                                                        |

Rail behavior (timing, limits, returns) lives on the rail pages: [ACH](/docs/rails/ach), [Fedwire](/docs/rails/fedwire), [SWIFT](/docs/rails/swift), [SEPA](/docs/rails/sepa), [Faster Payments](/docs/rails/fps), [Blockchain](/docs/rails/blockchain).

## List payouts

Fetches all payouts on your account. Filter and paginate as needed.

<Tabs>
  <Tab title="2026-05-01">
    ```ts theme={null}
    import Augustus from '@augustusbank/typescript-sdk'

    const client = new Augustus()
    for await (const payout of client.payouts.list()) {
      // process payout
    }
    ```

    [**GET** `/v1/payouts` in the API Reference →](/api-reference/payouts/list-payouts)
  </Tab>

  <Tab title="2023-01-01">
    ```ts theme={null}
    import Ivy from '@getivy/node-sdk'

    const client = new Ivy()
    const { items } = await client.payouts.list({})
    for (const payout of items) {
      // process payout
    }
    ```

    [**POST** `/api/service/payout/list` in the API Reference →](/api-reference/payout/list-payouts)
  </Tab>
</Tabs>

## Retrieve a payout

Fetches the details of a single payout by its ID.

<Tabs>
  <Tab title="2026-05-01">
    ```ts theme={null}
    import Augustus from '@augustusbank/typescript-sdk'

    const client = new Augustus()
    const payout = await client.payouts.retrieve('payout_id')
    ```

    [**GET** `/v1/payouts/{id}` in the API Reference →](/api-reference/payouts/retrieve-payout)
  </Tab>

  <Tab title="2023-01-01">
    ```ts theme={null}
    import Ivy from '@getivy/node-sdk'

    const client = new Ivy()
    const payout = await client.payouts.retrieve({ id: 'payout_id' })
    ```

    [**POST** `/api/service/payout/retrieve` in the API Reference →](/api-reference/payout/retrieve-a-payout)
  </Tab>
</Tabs>

View payouts in the [Dashboard](https://dashboard.augustus.com/dashboard/payouts).

## Statuses

| Status      | Description                                                                                                          |
| ----------- | -------------------------------------------------------------------------------------------------------------------- |
| `initiated` | The payout was given to Augustus: checks are running, or it is queued for the network.                               |
| `submitted` | Handed to the payment rail and acknowledged; awaiting acceptance.                                                    |
| `sent`      | Accepted and sent on the rail. The rail pages state what this means per rail.                                        |
| `failed`    | Could not be completed after initiation or submission; funds remain in your account.                                 |
| `returned`  | Came back after it was sent; the funds are credited back to your account. See [Returned payouts](#returned-payouts). |

For international USD payouts over the correspondent network, see [SWIFT](/docs/rails/swift).

## Returned payouts

On rails with a return procedure, the receiving bank can send a payout back after it was sent, for example when the account is closed or the receiver refuses the payment. A return that references the original payment (ACH: a return entry with the trace number; SWIFT and Fedwire: a pacs.004 with the UETR) moves the payout to `returned`, fires the `payout.returned` webhook, and credits the full amount back to your account. International returns can arrive net of correspondent fees. Windows and reasons are rail-specific: see [ACH](/docs/rails/ach#returned-payouts), [SEPA](/docs/rails/sepa), and [SWIFT](/docs/rails/swift#returns).

Funds that come back as a fresh, unreferenced payment arrive as a new [deposit](/docs/payments/deposits) instead, and the original payout stays `sent`. This is the usual case on Fedwire: a settled wire is final, and a receiving bank that agrees to send funds back does so with a new wire; see [Finality and cancellation](/docs/rails/fedwire#finality-and-cancellation).

## Webhooks

Subscribe to payout events for real-time updates.

<Tabs>
  <Tab title="2026-05-01">
    ```ts theme={null}
    import Augustus from '@augustusbank/typescript-sdk'

    const client = new Augustus()
    const subscription = await client.webhookSubscriptions.create({
      url: 'https://your-server.com/webhooks',
      events: ['payout.initiated', 'payout.submitted', 'payout.sent', 'payout.failed', 'payout.returned'],
    })
    ```

    [**POST** `/v1/webhook_subscriptions` in the API Reference →](/api-reference/webhook-subscriptions/create-webhook-subscription)
  </Tab>

  <Tab title="2023-01-01">
    ```ts theme={null}
    import Ivy from '@getivy/node-sdk'

    const client = new Ivy()
    const subscription = await client.webhook.subscription.create({
      url: 'https://your-server.com/webhooks',
      events: ['payout.initiated', 'payout.paid', 'payout.failed'],
    })
    ```

    [**POST** `/api/service/webhook-subscription/create` in the API Reference →](/api-reference/webhook-subscription/create-a-webhook-subscription)
  </Tab>
</Tabs>

| Event              | Description                                                               |
| ------------------ | ------------------------------------------------------------------------- |
| `payout.initiated` | A payout was created and is being processed.                              |
| `payout.submitted` | The payout was handed to the payment rail.                                |
| `payout.sent`      | The payout was accepted and sent on the rail.                             |
| `payout.failed`    | The payout could not be completed. Inspect `payload.failure` for details. |
| `payout.returned`  | A sent payout came back; the funds are credited back to your account.     |

## FAQ

<AccordionGroup>
  <Accordion title="Which rail does a payout travel on?">
    EUR payouts go over [SEPA](/docs/rails/sepa), GBP over [Faster Payments](/docs/rails/fps), and USD over [ACH](/docs/rails/ach), [Fedwire](/docs/rails/fedwire), or [SWIFT](/docs/rails/swift) depending on the `rail` you select. USDC payouts settle on-chain; see [Blockchain](/docs/rails/blockchain).
  </Accordion>

  <Accordion title="Can I cancel a payout?">
    Not through the API. Once a payout is submitted to the network, cancellation is no longer possible; before submission, support may be able to stop it. The rail pages carry the specifics.
  </Accordion>

  <Accordion title="What happens when a payout fails?">
    The payout moves to `failed` and `payout.failed` fires. Funds remain in your account, and the `failure` field carries the reason.
  </Accordion>
</AccordionGroup>