Payouts

Send funds from an Augustus account to a saved counterparty: a bank destination for an individual or business, or a verified crypto wallet for USDC.

Supported currencies

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

Create a payout

Sending money is two API calls: save the destination once as a counterparty, then create the payout against its counterparty_id. The counterparty is reusable: for every later payout to the same destination, only the second call runs. Create a separate counterparty for each bank destination or wallet address.

2026-05-01
2023-01-01

New fiat counterparties created through the API start in active. New crypto counterparties start in pending and need review before payouts. The USDC example uses a saved counterparty and checks that it is active and unblocked. See Counterparty lifecycle for initial states, review and payment eligibility.

import Augustus from '@augustusbank/typescript-sdk'

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

import Augustus from '@augustusbank/typescript-sdk'

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

import Augustus from '@augustusbank/typescript-sdk'

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

import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus()
const counterparty = await client.counterparties.create({
  financial_address: {
    type: 'bic',
    bic: 'ANZBAU3MXXX',
    account_number: '12345678',
    account_holder_name: 'Acme Trading Pty Ltd',
    local_bank_code: '012003',
  },
  physical_address: {
    line_1: '1 Martin Place',
    city: 'Sydney',
    country_code: 'AU',
    postal_code: '2000',
  },
})
const payout = await client.payouts.create({
  account_id: 'your-usd-account-id',
  amount: '10000.00',
  currency: 'USD',
  rail: 'swift',
  counterparty_id: counterparty.id,
  unstructured_remittance_information: 'Invoice 1234',
})

import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus({ baseURL: 'https://api.sandbox.augustus.com' })
const counterparty = await client.counterparties.retrieve('your-crypto-counterparty-id')
if (counterparty.status !== 'active' || counterparty.blocked) {
  throw new Error('The crypto counterparty must be active and unblocked')
}
const payout = await client.payouts.create({
  account_id: 'your-usdc-wallet-id',
  amount: '1000.00',
  currency: 'USDC',
  counterparty_id: counterparty.id,
})

Find each Account ID in the Dashboard under Accounts → Details.

POST /v1/counterparties in the API Reference →POST /v1/payouts in the API Reference →

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 →

Key fields

Field	Behavior
`currency`	`USD`, `USDC`, `EUR`, or `GBP`.
`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_id`	ID of a saved counterparty. Save the destination with POST `/v1/counterparties` first. The counterparty’s `financial_address` follows the currency: `iban` for EUR and for international USD to IBAN countries, `sort_code` for GBP, `aba` for domestic USD, `bic` for international USD to non-IBAN countries, a `crypto_wallet` financial address for USDC. Every international USD payout, to an `iban` or a `bic` destination, needs a complete `physical_address` on the counterparty (`line_1`, `city`, `postal_code`, `country_code`); without it the payout fails.
`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, Fedwire, SWIFT, SEPA, Faster Payments, Blockchain.

List payouts

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

2026-05-01
2023-01-01

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 →

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 →

Retrieve a payout

Fetches the details of a single payout by its ID.

2026-05-01
2023-01-01

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 →

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 →

Tracking reference

tracking_reference holds the identifier the payment network assigned to the payout, as an object with a type and a value:

Rail	`type`	`value`
SWIFT	`uetr`	The UETR (Unique End-to-End Transaction Reference)
Fedwire	`imad`	The IMAD (Input Message Accountability Data)
ACH	`trace_number`	The 15-digit ACH trace number

"tracking_reference": {
  "type": "uetr",
  "value": "550e8400-e29b-41d4-a716-446655440000"
}

It is null when no reference is available yet, and on SEPA, Faster Payments and blockchain rails. Stablecoin payouts carry their on-chain hash in tx_hash. Quote the reference when you or your counterparty’s bank trace a payment. View payouts in the Dashboard.

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.

For international USD payouts over the correspondent network, see SWIFT.

Status transitions

From	To	When	Webhook
`initiated`	`submitted`	The rail acknowledged the payout.	`payout.submitted`
`initiated`	`sent`	Settled without a separate acknowledgement step, so `submitted` is skipped.	`payout.sent`
`initiated`	`failed`	Rejected before submission, for example by a compliance check.	`payout.failed`
`submitted`	`sent`	Accepted and sent on the rail.	`payout.sent`
`submitted`	`failed`	Rejected by the rail.	`payout.failed`
`sent`	`returned`	The receiving bank sent the payment back and Augustus matched it to this payout.	`payout.returned`

returned is final. failed ends normal processing; in exceptional cases Augustus corrects a payout from failed to sent after an investigation, and payout.sent fires. sent is final on the rail, but the payout can still move to returned when a matched return arrives, which can be days later; the rail pages give the windows. No other transition exists: a payout never moves from sent to failed, and a return that cannot be matched leaves the payout at sent and arrives as a new deposit. When to retrieve a payout. Every webhook payload is a full snapshot of the payout at the time of the event, so you do not need to retrieve the payout to learn its status. Deliveries can arrive out of order or more than once: rank the statuses initiated < submitted < sent < returned and ignore an event whose status ranks below the one you already stored. If you receive payout.sent after payout.failed, retrieve the payout rather than discarding the event. Otherwise retrieve the payout only when an event references one you do not know, or to catch up after your endpoint was unavailable. See Event ordering.

Returned payouts

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. What happens next depends on whether Augustus can match the return to the payout it undoes:

Linked. The return references the original payment (ACH: a return entry carrying the trace number; SWIFT and Fedwire: a pacs.004 carrying the UETR). The payout moves to returned, the payout.returned webhook fires, and the amount is credited back to your account as a transaction that points at the payout. No deposit is created.
Unlinked. The funds come back as a fresh, unreferenced payment. They arrive as a new deposit that looks like any other incoming transfer, and the 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.

International returns can arrive net of correspondent fees, so reconcile a return on its reference, never on the amount. Windows and reasons are rail-specific: see ACH, SEPA, and SWIFT.

Webhooks

Subscribe to payout events for real-time updates.

2026-05-01
2023-01-01

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 →

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 →

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

Which rail does a payout travel on?

EUR payouts go over SEPA, GBP over Faster Payments, and USD over ACH, Fedwire, or SWIFT depending on the rail you select. USDC payouts settle on-chain; see Blockchain.

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.

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.

Basics

Accounts

Transactions

Payments

Conversions

Loans

Supported currencies

Create a payout

Key fields

List payouts

Retrieve a payout

Tracking reference

Statuses

Status transitions

Returned payouts

Webhooks

FAQ

​Supported currencies

​Create a payout

​Key fields

​List payouts

​Retrieve a payout

​Tracking reference

​Statuses

​Status transitions

​Returned payouts

​Webhooks

​FAQ

Supported currencies

Create a payout

Key fields

List payouts

Retrieve a payout

Tracking reference

Statuses

Status transitions

Returned payouts

Webhooks

FAQ