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

USD deposits arrive over ACH or Fedwire, international USD wires over SWIFT; the deposit's `rail` field specifies over which rail the funds were received. Rail-specific behavior (timing, availability, returns) is documented in [ACH](/docs/rails/ach), [Fedwire](/docs/rails/fedwire), and [SWIFT](/docs/rails/swift).

## Stablecoin deposits

Your Augustus wallet address can be retrieved from the Dashboard under [Accounts → Details](https://dashboard.augustus.com/dashboard/accounts). Incoming deposits must come from a **linked wallet** on a supported chain; see [Blockchain](/docs/rails/blockchain).

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

## Statuses

A deposit is a record of money that arrived: it appears once the funds are final and has a single status.

| Status    | Description                                                                          |
| --------- | ------------------------------------------------------------------------------------ |
| `settled` | Funds arrived and were credited to your account; `settled_at` carries the timestamp. |

A deposit never changes status after that. Returning it does not touch the deposit: the return is its own resource with its own lifecycle, linked through the deposit's `returns` array; see [Returns](#returns). The sender is referenced on the deposit as its `counterparty_id`.

## Webhook events

Subscribe to the following events to be notified about deposits and returns:

| Event              | Description                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| `deposit.settled`  | A new deposit was credited to one of your accounts.                                                |
| `return.initiated` | A return was created and is being processed.                                                       |
| `return.submitted` | The return was handed to the payment rail.                                                         |
| `return.sent`      | The return was accepted and sent on the rail.                                                      |
| `return.failed`    | The return could not be completed; the funds remain in your account.                               |
| `return.returned`  | A sent return came back from the sender's bank, and the funds were credited to your account again. |

A return is an outbound payment, so the `return.*` events mirror the `payout.*` events one-to-one: same statuses, same order. See [Returns](#returns).

## Retrieve a deposit

Get a deposit ID from the `deposit.settled` webhook payload or by [listing deposits](/api-reference/deposits/list-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. Use it for deposits you cannot apply: an unexpected payment, a sender error, or funds you are not able to accept. The full amount travels back over the rail the deposit arrived on, to the account it came from. The rail pages state whether a return can be created through the API, within which window, and what the sender sees.

A return is an outbound payment with the same lifecycle as a [payout](/docs/payments/payouts#statuses): `initiated`, then `submitted`, then `sent`; `failed` when it could not be completed. A sent return that comes back from the sender's bank moves to `returned`, which is final: to send the money back again, create a new payout. The deposit itself stays `settled` throughout. 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?">
    The API has no concept of a matched or unmatched deposit: the payment is accepted and recorded like any other. Reconcile it against your own records, or [return the funds](#returns) if you can't apply it.
  </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/payments/payouts).
  </Accordion>
</AccordionGroup>