Deposits

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 crypto counterparty on a supported chain.
An FBO account, whose payment details are issued in your customer’s name. See FBO 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, Fedwire, and SWIFT.

Stablecoin deposits

Your Augustus wallet address can be retrieved from the Dashboard under Accounts → Details. Incoming deposits must come from a crypto counterparty on a supported chain; see Blockchain.

Verify the address, chain, and amount before sending. Deposits from an address that is not verified yet stay pending until the counterparty is verified; transfers on an unsupported chain may be lost.

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. The sender is referenced on the deposit as its counterparty_id where the rail delivers the sender’s account details. ACH does not share the originator’s account number, so inbound ACH deposits have counterparty_id: null.

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.

Retrieve a deposit

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

2026-05-01
2023-01-01

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 →

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 →

tracking_reference holds the identifier the payment network assigned to the incoming payment, as an object with a type and a value: uetr on SWIFT, imad on Fedwire, trace_number on ACH. It is null when no reference is available, and stablecoin deposits carry their on-chain hash in tx_hash. See Tracking reference for the format.

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. It references the parent deposit and emits return.* webhook events as it progresses; the deposit itself stays settled throughout.

Status	Meaning	Webhook
`initiated`	Augustus accepted the return: checks are running, or it is queued for the rail.	`return.initiated`
`submitted`	Handed to the rail and acknowledged.	`return.submitted`
`sent`	Accepted and sent on the rail; the funds have left your account.	`return.sent`
`failed`	Could not be completed after initiation or submission; the funds stay in your account.	`return.failed`
`returned`	The sender’s bank sent the return back; the funds are in your account again.	`return.returned`

The transitions are the same as for payouts, see Status transitions: initiated to submitted to sent, failed from initiated or submitted, and sent to returned. failed and returned are final: to send the money back again, create a new payout.

Create a return

2026-05-01
2023-01-01

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 →

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 →

Retrieve a return

2026-05-01
2023-01-01

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 →

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 →

FAQ

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 if you can’t apply it.

How do deposits affect my balance?

Each successful deposit immediately increases the account’s available balance. See Balances.

Can I partially return a deposit?

No. Only full returns are supported. To send back a partial amount, use a payout.

Basics

Accounts

Transactions

Payments

Conversions

Loans

Stablecoin deposits

Statuses

Webhook events

Retrieve a deposit

Returns

Create a return

Retrieve a return

FAQ

​Stablecoin deposits

​Statuses

​Webhook events

​Retrieve a deposit

​Returns

​Create a return

​Retrieve a return

​FAQ

Stablecoin deposits

Statuses

Webhook events

Retrieve a deposit

Returns

Create a return

Retrieve a return

FAQ