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

# Deposits

> Receive incoming fiat or crypto transfers directly into your accounts.

A deposit is any incoming transfer credited to one of your accounts. Augustus creates a deposit record when funds arrive on:

* An **operating account**, using its rail-specific payment details (IBAN, sort code, ABA).
* A **stablecoin wallet**, from a [linked wallet](/docs/accounts/wallets#linked-wallets) on a supported chain.
* A **virtual account**, whose payment details are issued in your customer's name. See [Virtual accounts](/docs/accounts/virtual-accounts).

You receive a webhook for every deposit. Reconcile or return it from there.

<Warning>
  By default your account may not be enabled for inbound deposits and payments could be auto-returned. Turn off auto-returns under **Settings → Money**, or contact support to enable deposits on the accounts you want to receive funds on.
</Warning>

## Stablecoin deposits

Copy your wallet address from the Dashboard under **Accounts → Details**. Senders must transfer from a **linked wallet** on a supported chain.

<Warning>
  Verify the address, chain, and amount before sending. Transfers from non-linked addresses or unsupported chains may be lost.
</Warning>

## Webhook events

Subscribe to the following events to be notified when deposits and returns change state:

| Event              | Description                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| `deposit.received` | A new deposit arrived on one of your accounts.                                                       |
| `return.initiated` | A return was initiated for a deposit.                                                                |
| `return.paid`      | The return was processed successfully.                                                               |
| `return.failed`    | The return could not be completed.                                                                   |
| `return.returned`  | A previously paid return was reversed or returned, and the funds were credited back to your account. |

## Retrieve a deposit

Get a deposit ID from the `deposit.received` webhook payload or by listing deposits.

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

    const client = new Augustus()
    const deposit = await client.deposits.retrieve('your-deposit-id')
    ```

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

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

    const client = new Ivy()
    const deposit = await client.deposits.retrieve({ id: 'your-deposit-id' })
    ```

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

## Returns

A return sends a deposit back to the original sender. Returns reference the parent deposit and emit `return.*` webhook events as they progress.

### Create a return

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

    const client = new Augustus()
    const ret = await client.returns.create({
      deposit_id: 'your-deposit-id',
    })
    ```

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

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

    const client = new Ivy()
    const ret = await client.returns.create({
      depositId: 'your-deposit-id',
    })
    ```

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

### Retrieve a return

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

    const client = new Augustus()
    const ret = await client.returns.retrieve('your-return-id')
    ```

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

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

    const client = new Ivy()
    const ret = await client.returns.retrieve({ id: 'your-return-id' })
    ```

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

## FAQ

<AccordionGroup>
  <Accordion title="What happens if a deposit doesn't match what I expected?">
    With Deposits enabled, the payment is accepted and recorded as an unmatched deposit. Reconcile it in your own system or return the funds. Without Deposits enabled, mismatched payments may be returned automatically.
  </Accordion>

  <Accordion title="How do deposits affect my balance?">
    Each successful deposit immediately increases the account's available balance. See [Balances](/docs/accounts/balances).
  </Accordion>

  <Accordion title="Can I partially return a deposit?">
    No — only full returns are supported. To send back a partial amount, use a [payout](/docs/payout/payout).
  </Accordion>

  <Accordion title="Why are deposits in Test Mode not working?">
    By default, your account is set to auto-return funds. Turn off auto-returns under **Settings → Money** to receive test deposits.
  </Accordion>
</AccordionGroup>