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.
Draft. This guide describes the proposed interface for Augustus international USD payments. The API resource names, fields, statuses, and webhook event shapes are subject to change. Share feedback or questions with will@augustus.com. Use cases
International payouts unlock four core flows:
- User withdrawals. Pay your end users out to international USD accounts they hold elsewhere.
- Paying invoices globally. Settle bills with international suppliers, contractors, and vendors in USD.
- Settling trades. Send the USD leg of trades to international counterparties — exchanges, OTC desks, market makers.
- Internal treasury. Move funds between group entities globally to manage liquidity.
How it works
Every international USD payment ultimately clears at the Federal Reserve. Augustus’s direct Fed master account access means we initiate the US leg directly.
- You instruct. Your system calls
POST /v1/payouts with the beneficiary, amount, and any supporting details.
- Augustus validates and routes. We screen, validate the payment data, and resolve the correspondent route.
- Augustus sends the payment. We route the payment through intermediary banks to the beneficiary bank, including the information of the ultimate beneficiary.
- You get real-time status. Payout status transitions surface via webhooks and the API; correspondent-level progress is available through a separate tracking resource linked to the payout.
- Funds reach the beneficiary. The beneficiary bank receives the funds and credits the end beneficiary’s account.
Account structure
International USD payments are supported on all Augustus account types:
| Type | When to use | What you get |
|---|
| DDA | Funds held in your own entity’s name. | A USD account number and routing details for sending and receiving in your name. |
| FBO | Funds held on behalf of your end users. | A master FBO account plus per-user virtual accounts. Each virtual account has its own number; international USD payments can be sent and received at virtual accounts. |
Sending USD internationally
A payout is an outgoing international USD payment from your Augustus account to an external beneficiary.
Create a payout
This guide focuses on international USD-specific fields. For authentication, idempotency, and error format, see Authentication, Idempotency, and Errors.
| Field | Type | Required | Description |
|---|
source_account_id | string | Yes | The Augustus account to debit. For me-to-me flows, use a virtual account in the end user’s name. |
rail | string | Yes | Payment scheme. Use "swift" for international USD payments. |
amount | string | Yes | Transfer amount as a string decimal (e.g. "10000.00"). |
currency | string | Yes | Three-letter ISO currency code. Use "USD". |
destination | object | Yes | Beneficiary details. See Destination. |
reference | string | No | Free-text reference forwarded to the beneficiary in the payment message (often surfaced as the remittance line). Keep it short — intermediary banks may truncate. |
swift | object | No | SWIFT-specific parameters. Required fields vary by corridor. See SWIFT object. |
metadata | object | No | Up to 10 key-value pairs of your own data. Returned on every payout response and webhook payload. |
Destination
International beneficiaries come in two flavours: IBAN-formatted accounts (mostly Europe and parts of MENA) and everything else.
IBAN beneficiary
"destination": {
"name": "Acme Trading GmbH",
"account_number": "DE89370400440532013000",
"address": {
"street": "Königsallee 1",
"city": "Düsseldorf",
"country": "DE",
"postal_code": "40212"
},
"entity_type": "business"
}
"destination": {
"name": "Acme Trading Pte Ltd",
"account_number": "0123456789",
"address": {
"street": "1 Raffles Place",
"city": "Singapore",
"country": "SG",
"postal_code": "048616"
},
"entity_type": "business",
"bank": {
"bic": "DBSSSGSGXXX"
}
}
| Field | Type | Required | Description |
|---|
name | string | Yes | Full legal name of the beneficiary. |
account_number | string | Yes | Beneficiary account number (IBAN or local format). |
address | object | Yes | Structured address with street, city, country (ISO 3166-1 alpha-2), and optionally state and postal_code. |
entity_type | string | No | "individual" or "business". Improves validation accuracy. |
bank | object | No | Beneficiary bank details. Resolved automatically from the account number (e.g. IBAN) where possible. See Beneficiary Bank object. |
Beneficiary Bank object
| Field | Type | Required | Description |
|---|
bic | string | Yes | SWIFT/BIC code of the beneficiary’s bank. |
name | string | No | Bank name. Resolved automatically from BIC if omitted. |
country | string | No | Bank country (ISO 3166-1 alpha-2). Resolved from BIC if omitted. |
SWIFT object
Optional SWIFT-specific parameters on the payout request. Required fields depend on the beneficiary corridor; your account manager can confirm the exact shape for your integration.
International Payout Routing
You provide the beneficiary. Augustus resolves the path:
- You provide the beneficiary details including name, account number, and address.
- Augustus uses Standard Settlement Instructions to identify the optimal route for the payment through the correspondent bank network.
- The resolved route — including any intermediary FIs — is returned in the payout response on the
routing field, so you have full visibility into the path your payment takes.
- As the payment moves through the route, correspondent-level updates are recorded on a tracking resource associated with the payout (not embedded in the payout object). See Tracking.
Optional customer-provided routing. For day one we plan to calculate the correspondent route in all cases. Passing an intermediary_bank object is possible on request.
International Payout Validation
Augustus validates every payout before submitting to the network. Catching formatting errors, missing fields, and sanctions hits before funds move reduces manual repair queues and protects your STP rate.
| Check | What it does |
|---|
| Beneficiary account verification | Confirms the account is open and able to receive funds at the specified bank, where supported. |
| Name matching | Cross-checks the beneficiary name against the account holder on record at the beneficiary bank, where supported. |
| Address formatting | Ensures the beneficiary address is structured correctly for the destination country. |
| BIC resolution | Validates the bank BIC and resolves the bank name and country. |
| Screening | Screens against OFAC, EU, and UN sanctions lists. |
Payout lifecycle
| Status | Description |
|---|
pending | Payout received. Augustus is validating data, screening, and resolving the route. |
submitted | Payment submitted to the network. |
in_transit | In flight on the correspondent network; status updates as the payment moves through correspondents. |
paid | Beneficiary bank has confirmed receipt and credited the beneficiary. |
failed | Validation or processing failure before submission. Funds remain in your account. The failure field carries the reason. |
canceled | Payout cancelled before submission (e.g. by manual review or your request via the dashboard). |
Tracking
Augustus provides end-to-end payment tracking via SWIFT GPI (Global Payments Innovation). Every SWIFT payout is assigned a UETR (Unique End-to-End Transaction Reference). As the payment moves through the correspondent chain, each bank in the path is required to report a status update — Augustus aggregates these into a tracking resource (a separate object from the payout) and surfaces updates in real time.
Use that resource to show progress to your end users without polling. It includes the current network status, a uetr where available, and an events array that grows as each correspondent reports a hop. Full API shapes will live in the API reference when the tracking endpoints ship.
- The beneficiary must be able to receive USD. If the beneficiary holds a non-USD account, the intermediary bank may FX the payment downstream.
- Submit payouts 24/7. Payments submitted outside of Fedwire operating hours queue and clear automatically at the next opening.
For incoming bank transfers and deposit rails, see Deposits.
Webhook events
Subscribe to these events for international payouts. For payload envelope, signature verification, retry policy, and replay, see Webhooks.
| Event | When |
|---|
payout.created | Payout accepted by the API and queued for validation. |
payout.initiated | Payout submitted to the network. |
payout.paid | Beneficiary credited. |
payout.failed | Validation or processing failure. The payload failure field carries the reason. |
return.initiated | Beneficiary chain has returned the payment. |
return.received | Returned funds have credited back to your source account. |
Webhook payload structure
{
"id": "evt_8fn29dk3",
"type": "payout.paid",
"payload": {
"id": "po_9vn38dk2",
"type": "payout",
"source_account_id": "acct_4kd82ms0",
"rail": "swift",
"amount": "15000.00",
"currency": "USD",
"status": "paid",
"destination": {
"name": "Acme Trading Ltd"
},
"completed_at": "2026-07-15T15:45:00Z"
},
"date": "2026-07-15T15:45:01Z"
}
Out of scope today
The following are intentionally not in MVP. We are tracking each as roadmap items based on early customer feedback:
- Customer-initiated SWIFT messaging. Initiation is via API only.
- Customer-provided routing. Augustus calculates routing from SwiftRef SSI data.
- Non-USD clearing. Augustus only sends and receives international payments in USD.
