Simulations

In the sandbox there are no real banks or payment networks, so deposits never arrive and payouts never settle on their own. Simulation endpoints (/v1/simulations/*) let you drive those outcomes yourself, so you can build and test a complete money movement flow end to end before going live. This walkthrough takes a new integration through the full lifecycle: you open an account (operating or virtual, whichever fits your product), fund it with a simulated incoming deposit, and pay out to a counterparty. You advance each step yourself with the simulation endpoints.

In this guide

Prerequisites

The scopes and sandbox API key you need before you start.

Core walkthrough

Open an account, receive a simulated deposit, and send a payout.

Failed and returned payouts

Reject a payout before sending or return one after it is sent.

Freeze, drain, and close

Wind down an account or an account program end to end.

Return a deposit you received

Send a received deposit back to its sender and follow the return.

SWIFT

What differs for international USD: counterparty requirements and simulation rules.

Conversions

Convert funds between your accounts.

What you’ll build

Open an account (operating or virtual).
Receive a simulated deposit and watch it settle.
Save a payout counterparty.
Send a payout and advance it to sent.

Prerequisites

A sandbox API key with these scopes (or full_access). See Scopes and inspect your key with GET /v1/api_key.

Scope	Used for
`account_holders:write`	Creating an account holder (virtual account flow)
`accounts:read`	Reading account details
`accounts:write`	Creating a virtual account (virtual account flow)
`conversions:read`	Reading conversion details
`conversions:write`	Creating conversions
`counterparties:write`	Saving the payout destination
`deposits:read`	Confirming the deposit settled
`events:read`	Observing webhook events (optional)
`payouts:read`	Reading payout status
`payouts:write`	Creating the payout
`simulations:write`	Creating the account, deposit, and payout outcomes
`transactions:read`	Listing the account’s booked movements

Steps

Configure your environment

The SDK reads its configuration from environment variables, so point it at the sandbox.

export AUGUSTUS_API_KEY="sandbox.your_key"
export AUGUSTUS_BASE_URL="https://api.sandbox.augustus.com"

import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus()

Open an account

Pick the account model that matches your product and expand it. Both accounts come back ready to receive a deposit, and every step after this one is identical: they all run against the ACCOUNT_ID you capture here.

Operating account: one account you hold directly. Simplest option, good for treasury or a single balance.
Virtual account: a dedicated account per end customer (embedded-banking or FBO model), created under an account program and tied to an account holder.

Operating account

Create an operating (DDA) account. In the sandbox this is a single call; the account comes back active with its own US payment details.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/accounts" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Operating USD", "type": "operating" }'

const created = await client.simulations.accounts.create({
  label: 'Operating USD',
  type: 'operating',
})

const accountId = created.account_id

The response returns the new account’s ID:

{
  "type": "account_simulation",
  "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Capture the returned ID as ACCOUNT_ID for the steps below:

export ACCOUNT_ID="a1b2c3d4-..."

POST /v1/simulations/accounts in the API Reference →

Virtual account

A virtual account belongs to an account program and an account holder, so you create those two first, then the account itself.

Create an account program

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/account_programs" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Customer USD program", "type": "fbo_program" }'

const program = await client.simulations.accountPrograms.create({
  label: 'Customer USD program',
  type: 'fbo_program',
})

const accountProgramId = program.account_program_id

Capture the returned ID for the following steps:

export ACCOUNT_PROGRAM_ID="..."

POST /v1/simulations/account_programs in the API Reference →

Create an account holder

Provide the beneficiary’s details. The shape follows country_of_citizenship: use the US individual shape below when it is US, the non-US individual shape for any other country, and the business shape when holder_type is business.

curl -X POST "$AUGUSTUS_BASE_URL/v1/account_holders" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_program_id": "'"$ACCOUNT_PROGRAM_ID"'",
    "holder_type": "natural_person",
    "beneficiary_data": {
      "legal_name": "Jane Doe",
      "date_of_birth": "1990-01-01",
      "country_of_citizenship": "US",
      "residential_address": {
        "line_1": "123 Main St",
        "line_2": null,
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country_code": "US"
      },
      "identification": { "type": "ssn", "value": "123-12-1234" }
    }
  }'

const holder = await client.accountHolders.create({
  account_program_id: accountProgramId,
  holder_type: 'natural_person',
  beneficiary_data: {
    legal_name: 'Jane Doe',
    date_of_birth: '1990-01-01',
    country_of_citizenship: 'US',
    residential_address: {
      line_1: '123 Main St',
      line_2: null,
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94105',
      country_code: 'US',
    },
    identification: { type: 'ssn', value: '123-12-1234' },
  },
})

const accountHolderId = holder.id

Capture the returned ID for the following step:

export ACCOUNT_HOLDER_ID="..."

Account holders are processed asynchronously. See the full beneficiary_data schemas (US individual, non-US individual, business) in the POST /v1/account_holders API Reference →.

Create the virtual account

curl -X POST "$AUGUSTUS_BASE_URL/v1/accounts" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_program_id": "'"$ACCOUNT_PROGRAM_ID"'",
    "account_holder_id": "'"$ACCOUNT_HOLDER_ID"'"
  }'

const account = await client.accounts.create({
  account_program_id: accountProgramId,
  account_holder_id: accountHolderId,
})

const accountId = account.id

Capture the returned account ID as ACCOUNT_ID for the steps below:

export ACCOUNT_ID="..."

POST /v1/accounts in the API Reference →

For the full virtual-accounts model, see Virtual accounts.

Read the account's payment details

Retrieve the account to see its ABA payment details (US routing and account number). These are the details a sender would use to pay into the account.

curl "$AUGUSTUS_BASE_URL/v1/accounts/$ACCOUNT_ID" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY"

const account = await client.accounts.retrieve(accountId)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "account",
  "currency": "USD",
  "status": "active",
  "asset_type": "fiat",
  "label": "Operating USD",
  "financial_addresses": [
    {
      "type": "aba",
      "routing_number": "110000000",
      "account_number": "000123456789",
      "account_holder_name": "Acme Sandbox Ltd."
    }
  ],
  "created_at": "2026-05-01T10:00:00Z",
  "updated_at": "2026-05-01T10:00:00Z"
}

GET /v1/accounts/{id} in the API Reference →

Simulate an incoming deposit

Simulate a deposit arriving over Fedwire from an external sender. A wire carries the originator’s account details, so you provide them as the counterparty. The currency must match the account currency. Give it an unstructured_remittance_information value you can recognize later. You use it to find the settled deposit.

Deposits and payouts support the ach, fedwire, and swift rails. ACH does not carry the sender’s account details, so use fedwire when you want to attach a counterparty. SWIFT deposit simulations require a counterparty with an iban financial address. See ACH, Fedwire, and SWIFT.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/deposits" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "'"$ACCOUNT_ID"'",
    "amount": "5000.00",
    "currency": "USD",
    "rail": "fedwire",
    "unstructured_remittance_information": "guide-deposit-001",
    "counterparty": {
      "financial_address": {
        "type": "aba",
        "routing_number": "021000021",
        "account_number": "987654321",
        "account_holder_name": "Payer Inc."
      }
    }
  }'

await client.simulations.deposits.create({
  account_id: accountId,
  amount: '5000.00',
  currency: 'USD',
  rail: 'fedwire',
  unstructured_remittance_information: 'guide-deposit-001',
  counterparty: {
    financial_address: {
      type: 'aba',
      routing_number: '021000021',
      account_number: '987654321',
      account_holder_name: 'Payer Inc.',
    },
  },
})

POST /v1/simulations/deposits in the API Reference →

Dashboard equivalent: Payments → Deposits → Create deposit, pick the account, amount, reference, and rail (ACH, Fedwire, or SWIFT).

Confirm the deposit settled

Deposits are processed asynchronously and appear once they reach settled. Poll the deposits list and match on the remittance information you set.

curl "$AUGUSTUS_BASE_URL/v1/deposits" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY"

async function waitForDeposit(reference: string) {
  for (let attempt = 0; attempt < 20; attempt++) {
    const page = await client.deposits.list()
    const deposit = page.data.find(
      (d) => d.unstructured_remittance_information === reference,
    )
    if (deposit?.status === 'settled') return deposit
    await new Promise((resolve) => setTimeout(resolve, 500))
  }
  throw new Error('Deposit did not settle in time')
}

const deposit = await waitForDeposit('guide-deposit-001')

The settled deposit is credited to your account:

{
  "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
  "type": "deposit",
  "status": "settled",
  "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": "5000.00",
  "currency": "USD",
  "counterparty_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "unstructured_remittance_information": "guide-deposit-001",
  "tracking_reference": null,
  "rail": "fedwire",
  "tx_hash": null,
  "returns": [],
  "settled_at": "2026-05-01T10:01:00Z"
}

GET /v1/deposits in the API Reference →

Save a payout counterparty

A payout is always sent to a saved counterparty, so create one first. For a payout over ACH or Fedwire, use an aba financial address.

curl -X POST "$AUGUSTUS_BASE_URL/v1/counterparties" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading LLC",
    "entity_type": "business",
    "financial_address": {
      "type": "aba",
      "routing_number": "021000021",
      "account_number": "123456789",
      "account_holder_name": "Acme Trading LLC"
    }
  }'

const counterparty = await client.counterparties.create({
  name: 'Acme Trading LLC',
  entity_type: 'business',
  financial_address: {
    type: 'aba',
    routing_number: '021000021',
    account_number: '123456789',
    account_holder_name: 'Acme Trading LLC',
  },
})

const counterpartyId = counterparty.id

Capture the returned ID for the following step (the create response returns it as id):

export COUNTERPARTY_ID="..."

POST /v1/counterparties in the API Reference →

Create a payout

Debit your account and send funds to the counterparty. Reference the counterparty by counterparty_id; the rail is validated against the counterparty’s financial address and selected automatically when omitted.

curl -X POST "$AUGUSTUS_BASE_URL/v1/payouts" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "'"$ACCOUNT_ID"'",
    "amount": "2500.00",
    "currency": "USD",
    "counterparty_id": "'"$COUNTERPARTY_ID"'",
    "rail": "fedwire",
    "unstructured_remittance_information": "Invoice 1234"
  }'

const payout = await client.payouts.create({
  account_id: accountId,
  amount: '2500.00',
  currency: 'USD',
  counterparty_id: counterpartyId,
  rail: 'fedwire',
  unstructured_remittance_information: 'Invoice 1234',
})

const payoutId = payout.id

The payout is created as initiated and moves to submitted while it is in flight.

Capture the returned ID for the following step (the create response returns it as id):

export PAYOUT_ID="..."

POST /v1/payouts in the API Reference →

Simulate a successful send

In production the payment network settles the payout. In the sandbox you advance it yourself. Simulate a successful send.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/payouts/$PAYOUT_ID/send" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

await client.simulations.payouts.send(payoutId)

POST /v1/simulations/payouts/{id}/send in the API Reference →

Dashboard equivalent: open the payout under Payments → Payouts and use Sandbox Tools → Simulate payout → succeeded. The same menu offers failed and returned, matching the reject and return simulations below.

Poll until the payout is sent

Retrieve the payout until its status reaches sent.

curl "$AUGUSTUS_BASE_URL/v1/payouts/$PAYOUT_ID" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY"

async function waitForPayoutSent(id: string) {
  for (let attempt = 0; attempt < 20; attempt++) {
    const current = await client.payouts.retrieve(id)
    if (current.status === 'sent') return current
    await new Promise((resolve) => setTimeout(resolve, 500))
  }
  throw new Error('Payout did not reach sent in time')
}

const sent = await waitForPayoutSent(payoutId)

GET /v1/payouts/{id} in the API Reference →

Review the account's transactions

Every settled movement is recorded as a transaction. List them for your account to see the full ledger: the incoming deposit as a credit and the outgoing payout as a debit. Each transaction’s source links back to the deposit or payout that created it (null when it does not map to a retrievable resource). account_id is required. Narrow the results with the optional booked_at.gte and booked_at.lte filters.

curl "$AUGUSTUS_BASE_URL/v1/transactions?account_id=$ACCOUNT_ID" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY"

const transactions = await client.transactions.list({ account_id: accountId })

{
  "data": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "type": "transaction",
      "side": "debit",
      "status": "booked",
      "amount": "2500.00",
      "currency": "USD",
      "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "source": {
        "type": "payout",
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
      },
      "counterparty": {
        "financial_address": {
          "type": "aba",
          "routing_number": "021000021",
          "account_number": "123456789",
          "account_holder_name": "Acme Trading LLC"
        },
        "physical_address": null
      },
      "counterparty_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "unstructured_remittance_information": "Invoice 1234",
      "tracking_reference": null,
      "rail": "fedwire",
      "tx_hash": null,
      "booked_at": "2026-05-01T10:02:00Z"
    },
    {
      "id": "e9d8c7b6-a5f4-7890-abcd-ef1234567890",
      "type": "transaction",
      "side": "credit",
      "status": "booked",
      "amount": "5000.00",
      "currency": "USD",
      "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "source": {
        "type": "deposit",
        "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890"
      },
      "counterparty": {
        "financial_address": {
          "type": "aba",
          "routing_number": "021000021",
          "account_number": "987654321",
          "account_holder_name": "Payer Inc."
        },
        "physical_address": null
      },
      "counterparty_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "unstructured_remittance_information": "guide-deposit-001",
      "tracking_reference": null,
      "rail": "fedwire",
      "tx_hash": null,
      "booked_at": "2026-05-01T10:01:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "has_previous": false,
  "previous_cursor": null
}

You’ve now completed the full lifecycle end to end: account, deposit, payout, and the transactions that record them.GET /v1/transactions in the API Reference →

Simulate a failed or returned payout

Beyond the happy path, you can drive failure outcomes to test how your integration reacts.

Reject a payout before it is sent

While a payout is still submitted (before you simulate a send), simulate the network rejecting it. The payout moves to failed and the funds are released back to your account. Use invalid_routing_number for domestic rails or invalid_account_format for a SWIFT rejection.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/payouts/$PAYOUT_ID/reject" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "invalid_routing_number" }'

await client.simulations.payouts.reject(payoutId, {
  reason: 'invalid_routing_number',
})

POST /v1/simulations/payouts/{id}/reject in the API Reference →

Return a payout after it is sent

After a payout reaches sent, simulate the receiving bank returning it. The original payout stays sent; the returned funds arrive as a new standalone deposit (a credit transaction) on your account. Valid reasons are account_closed, invalid_account_format, invalid_routing_number, account_blocked, and unknown.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/payouts/$PAYOUT_ID/return" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "account_closed" }'

await client.simulations.payouts.return(payoutId, {
  reason: 'account_closed',
})

POST /v1/simulations/payouts/{id}/return in the API Reference →The returned funds show up as a new deposit rather than a change to the payout. List your deposits to find it:

curl "$AUGUSTUS_BASE_URL/v1/deposits" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY"

const deposits = await client.deposits.list()

GET /v1/deposits in the API Reference →

Return a deposit you received

A deposit you do not want to keep (an unexpected sender, a wrong amount) is sent back with a return. Returns are their own resource with the payout lifecycle: initiated → sent, then failed if the network rejects it or returned if the sender’s bank sends it back. The deposit itself stays settled; the return is linked to it and debits your account when it is sent.

Create the return

Pass the deposit_id of a settled deposit. The return goes back over the rail the deposit arrived on; you do not choose a rail or a reason code.

curl -X POST "$AUGUSTUS_BASE_URL/v1/returns" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "deposit_id": "'"$DEPOSIT_ID"'" }'

const deposit_return = await client.returns.create({ deposit_id: depositId })

POST /v1/returns in the API Reference →

Follow the return

A new return stays initiated until you drive it, the same way as a payout: POST /v1/simulations/returns/{id}/send makes it sent, /reject (with a reason) makes it failed, and /return on a sent return plays the sender’s bank sending it back: the return moves to returned and the funds are credited to your account again. Retrieve the return to follow each step.

curl "$AUGUSTUS_BASE_URL/v1/returns/$RETURN_ID" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY"

const current = await client.returns.retrieve(deposit_return.id)

GET /v1/returns/{id} in the API Reference →

Dashboard equivalent: open the deposit under Payments → Deposits and use Return in its detail view.

SWIFT

International USD moves over SWIFT and follows the same simulations as the domestic rails, with two differences:

	Domestic (ACH, Fedwire)	SWIFT
Incoming deposit simulation	`counterparty` optional; `aba` sender	`rail: "swift"`; the sender must be a counterparty with an `iban` financial address, or a saved `counterparty_id`
Payout counterparty	`aba` financial address	`iban` (IBAN countries) or `bic` + `account_number` (+ `local_bank_code` where the country uses one), plus a `physical_address`

SWIFT is USD only in both directions: currency: "EUR" with rail: "swift" is rejected at creation. Payout simulations (send, reject, return) work the same way as for the domestic rails. Use invalid_account_format as the reject reason to mimic a correspondent bank refusing the beneficiary details. Field-level rules and country requirements are on the SWIFT rail page.

Save an international counterparty

An IBAN beneficiary with a physical address. For non-IBAN countries use type: "bic" with account_number instead.

curl -X POST "$AUGUSTUS_BASE_URL/v1/counterparties" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading B.V.",
    "entity_type": "business",
    "financial_address": {
      "type": "iban",
      "iban": "NL91ABNA0417164300",
      "account_holder_name": "Acme Trading B.V."
    },
    "physical_address": {
      "line_1": "Damrak 1",
      "city": "Amsterdam",
      "postal_code": "1012 LG",
      "country_code": "NL"
    }
  }'

const swiftCounterparty = await client.counterparties.create({
  name: 'Acme Trading B.V.',
  entity_type: 'business',
  financial_address: {
    type: 'iban',
    iban: 'NL91ABNA0417164300',
    account_holder_name: 'Acme Trading B.V.',
  },
  physical_address: {
    line_1: 'Damrak 1',
    city: 'Amsterdam',
    postal_code: '1012 LG',
    country_code: 'NL',
  },
})

const swiftCounterpartyId = swiftCounterparty.id

Capture the ID for the next steps:

export SWIFT_COUNTERPARTY_ID="..."

POST /v1/counterparties in the API Reference →

Send a SWIFT payout

Same call as a domestic payout, with rail: "swift". Then drive it with send, reject, or return as above.

curl -X POST "$AUGUSTUS_BASE_URL/v1/payouts" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "'"$ACCOUNT_ID"'",
    "amount": "100.00",
    "currency": "USD",
    "rail": "swift",
    "counterparty_id": "'"$SWIFT_COUNTERPARTY_ID"'",
    "unstructured_remittance_information": "Invoice 5678"
  }'

const swiftPayout = await client.payouts.create({
  account_id: accountId,
  amount: '100.00',
  currency: 'USD',
  rail: 'swift',
  counterparty_id: swiftCounterpartyId,
  unstructured_remittance_information: 'Invoice 5678',
})

POST /v1/payouts in the API Reference →

Receive an international wire

The sender has to be an IBAN counterparty: pass the saved counterparty_id, or an inline counterparty with an iban financial address.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/deposits" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "'"$ACCOUNT_ID"'",
    "amount": "250.00",
    "currency": "USD",
    "rail": "swift",
    "unstructured_remittance_information": "guide-swift-deposit-001",
    "counterparty_id": "'"$SWIFT_COUNTERPARTY_ID"'"
  }'

await client.simulations.deposits.create({
  account_id: accountId,
  amount: '250.00',
  currency: 'USD',
  rail: 'swift',
  unstructured_remittance_information: 'guide-swift-deposit-001',
  counterparty_id: swiftCounterpartyId,
})

POST /v1/simulations/deposits in the API Reference →

Scripted outcomes by beneficiary BIC

The sandbox also plays the legs a SWIFT payment travels after the first one. Once you send a SWIFT payout, the beneficiary’s bank decides what happens next. Three German test beneficiaries have scripted outcomes; save one as an iban counterparty with the BIC in the bic field and pay it. Any other reachable bank succeeds on every leg.

Beneficiary IBAN	BIC	Outcome after `sent`
`DE40700202700012345678`	`HYVEDEMMXXX`	The correspondent rejects the payment. Nothing comes back.
`DE45500604000012345678`	`GENODEFFXXX`	The correspondent rejects the payment and returns the funds.
`DE66370501980012345678`	`COLSDE33XXX`	Accepted up to the beneficiary bank, which returns the funds.

A scripted return behaves like a real one:

The payout moves to returned and the payout.returned webhook fires. No deposit is created: Augustus matches the return to the payout on the original payment reference and credits the amount back to your account. Follow it on the payout, not on the deposits list.
The re-credited amount is net of a fixed USD 10.00 return charge: a USD 100.00 payout puts USD 90.00 back on your account, while the payout itself keeps showing USD 100.00. Never reconcile a return by its amount.
A payout of USD 10.00 or less is consumed by the charge, so no return arrives and the rejection is final.

POST /v1/simulations/payouts/{id}/return is unaffected: the payout moves to returned and the full amount is credited back.

Freeze, drain, and close

Winding down an account or an account program follows the same sequence: freeze it, drain the residual balance to an external destination, settle the drain payout(s), then close it. A frozen account or program can be reactivated with the matching unfreeze endpoint before you close it.

Close an operating account

Freeze the account

Freezing stops new movements and is required before draining.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/accounts/$ACCOUNT_ID/freeze" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

await client.simulations.accounts.freeze(accountId)

POST /v1/simulations/accounts/{id}/freeze in the API Reference →Changed your mind before closing? Reactivate the account with unfreeze:

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/accounts/$ACCOUNT_ID/unfreeze" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

await client.simulations.accounts.unfreeze(accountId)

POST /v1/simulations/accounts/{id}/unfreeze in the API Reference →

Drain the residual balance

Drain sends the remaining balance to an external destination and returns the payout that carries it. Use an aba financial address for a USD destination.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/accounts/$ACCOUNT_ID/drain" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "type": "aba",
      "routing_number": "021000021",
      "account_number": "123456789",
      "account_holder_name": "Acme Trading LLC"
    }
  }'

const drain = await client.simulations.accounts.drain(accountId, {
  destination: {
    type: 'aba',
    routing_number: '021000021',
    account_number: '123456789',
    account_holder_name: 'Acme Trading LLC',
  },
})

const drainPayoutId = drain.payout_id

The response returns the drain payout’s ID:

{
  "type": "account_simulation",
  "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payout_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}

Capture the returned ID to settle it in the next step:

export DRAIN_PAYOUT_ID="..."

POST /v1/simulations/accounts/{id}/drain in the API Reference →

Settle the drain payout

Send the drain payout so the balance reaches zero, the same way you settle any payout.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/payouts/$DRAIN_PAYOUT_ID/send" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

await client.simulations.payouts.send(drainPayoutId)

POST /v1/simulations/payouts/{id}/send in the API Reference →

Close the account

With the balance at zero you can close the account. Valid reasons are client_request and aml_risk_fraud.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/accounts/$ACCOUNT_ID/close" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "client_request" }'

await client.simulations.accounts.close(accountId, {
  reason: 'client_request',
})

POST /v1/simulations/accounts/{id}/close in the API Reference →

Close an account program

Closing a program winds down every virtual account under it. Drain returns one payout per funded account, so settle each returned ID.

Freeze the program

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/account_programs/$ACCOUNT_PROGRAM_ID/freeze" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

await client.simulations.accountPrograms.freeze(accountProgramId)

POST /v1/simulations/account_programs/{id}/freeze in the API Reference →Changed your mind before closing? Reactivate the program and its accounts with unfreeze:

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/account_programs/$ACCOUNT_PROGRAM_ID/unfreeze" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

await client.simulations.accountPrograms.unfreeze(accountProgramId)

POST /v1/simulations/account_programs/{id}/unfreeze in the API Reference →

Drain the program

Drain every frozen account under the program to an external destination. The response returns one payout ID per funded account.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/account_programs/$ACCOUNT_PROGRAM_ID/drain" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "type": "aba",
      "routing_number": "021000021",
      "account_number": "123456789",
      "account_holder_name": "Acme Trading LLC"
    }
  }'

const drain = await client.simulations.accountPrograms.drain(accountProgramId, {
  destination: {
    type: 'aba',
    routing_number: '021000021',
    account_number: '123456789',
    account_holder_name: 'Acme Trading LLC',
  },
})

const drainPayoutIds = drain.payout_ids

The response returns one payout ID per funded account:

{
  "type": "account_program_simulation",
  "account_program_id": "e5f6a7b8-c9d0-1234-ef01-234567890123",
  "payout_ids": [
    "c3d4e5f6-a7b8-9012-cdef-123456789012"
  ]
}

POST /v1/simulations/account_programs/{id}/drain in the API Reference →

Settle each drain payout

Send every payout returned by the drain so each account balance reaches zero.

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/payouts/$DRAIN_PAYOUT_ID/send" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

for (const id of drainPayoutIds) {
  await client.simulations.payouts.send(id)
}

POST /v1/simulations/payouts/{id}/send in the API Reference →

Close the program

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/account_programs/$ACCOUNT_PROGRAM_ID/close" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "client_request" }'

await client.simulations.accountPrograms.close(accountProgramId, {
  reason: 'client_request',
})

POST /v1/simulations/account_programs/{id}/close in the API Reference →

Conversions

Prerequisites

Make sure you have USD and USDC accounts. Conversions can be done in both directions. The example below shows a conversion of 10 USD to 10 USDC.Note the per-operation $1,000.00 and 24h $10,000.00 net sandbox limits.

Create a conversion

curl -X POST "$AUGUSTUS_BASE_URL/v1/conversions" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "source_account_id": "'"$ACCOUNT_USD_ID"'",
    "target_account_id": "'"$ACCOUNT_USDC_ID"'",
    "source_amount": "10.00",
    "metadata": {}
  }'

const conversion = await client.conversions.create({
  source_account_id: UsdAccountId,
  target_account_id: UsdcAccountId,
  source_amount: '10',
  metadata: {},
})
const conversionId = conversion.id

Capture the returned ID for the following steps:

export CONVERSION_ID="..."

Simulate outcome

Success

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/conversions/$CONVERSION_ID/complete" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json"

await client.simulations.conversions.complete(conversionId)

Failure

curl -X POST "$AUGUSTUS_BASE_URL/v1/simulations/conversions/$CONVERSION_ID/fail" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json"

await client.simulations.conversions.fail(conversionId)

Get conversion

curl -X GET "$AUGUSTUS_BASE_URL/v1/conversions/$CONVERSION_ID" \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "Content-Type: application/json"

await client.conversions.retrieve(conversionId)

{
  "id": "74810e2a-895d-46f2-84b9-dc1f2bce186e",
  "type": "conversion",
  "status": "completed",
  "source_amount": "10.00",
  "target_amount": "10.000000",
  "source_account_id": "8a5b0543-20fb-4a25-b1c3-8e635f00c41e",
  "target_account_id": "54101be7-a4d1-4ab9-acfb-7c73ec40bc0a",
  "metadata": {},
  "created_at": "2026-09-04T14:16:06.444Z",
  "updated_at": "2026-09-04T14:17:59.387Z",
  "completed_at": "2026-09-04T14:17:59.387Z"
}

If you simulate conversion failure, its status will be updated immediately. Otherwise, a conversion implies an on-chain transaction, it might take some time to transition from pending to the terminal state.

Getting Started

API Access

Accounts

Reconciliation

Payments

Conversions

Webhooks

Sandbox Simulations

In this guide

Prerequisites

Core walkthrough

Failed and returned payouts

Freeze, drain, and close

Return a deposit you received

SWIFT

Conversions

What you’ll build

Prerequisites

Steps

Simulate a failed or returned payout

Return a deposit you received

SWIFT

Scripted outcomes by beneficiary BIC

Freeze, drain, and close

Conversions

​In this guide

Prerequisites

Core walkthrough

Failed and returned payouts

Freeze, drain, and close

Return a deposit you received

SWIFT

Conversions

​What you’ll build

​Prerequisites

​Steps

​Simulate a failed or returned payout

​Return a deposit you received

​SWIFT

​Scripted outcomes by beneficiary BIC

​Freeze, drain, and close

​Conversions

In this guide

What you’ll build

Prerequisites

Steps

Simulate a failed or returned payout

Return a deposit you received

SWIFT

Scripted outcomes by beneficiary BIC

Freeze, drain, and close

Conversions