# Create account holder Source: https://docs.augustus.com/api-reference/account-holders/create-account-holder https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/account_holders Creates a new account holder and starts asynchronous processing. # List account holders Source: https://docs.augustus.com/api-reference/account-holders/list-account-holders https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/account_holders Lists account holders for the merchant with cursor-based pagination. # Retrieve account holder Source: https://docs.augustus.com/api-reference/account-holders/retrieve-account-holder https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/account_holders/{id} Retrieves an account holder by ID. # Update account holder Source: https://docs.augustus.com/api-reference/account-holders/update-account-holder https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/account_holders/{id} Replaces the beneficiary details of an existing account holder. # List account programs Source: https://docs.augustus.com/api-reference/account-programs/list-account-programs https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/account_programs Lists account programs for the merchant with cursor-based pagination. # Retrieve account program Source: https://docs.augustus.com/api-reference/account-programs/retrieve-account-program https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/account_programs/{id} Retrieves an account program by ID. # Retrieve account program balance Source: https://docs.augustus.com/api-reference/account-programs/retrieve-account-program-balance https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/account_programs/{id}/balance Returns the aggregated available balance for all virtual accounts under the account program. # Close account Source: https://docs.augustus.com/api-reference/accounts/close-account https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/accounts/{id}/close Closes an account # Create account Source: https://docs.augustus.com/api-reference/accounts/create-account https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/accounts Creates a new account. # Freeze account Source: https://docs.augustus.com/api-reference/accounts/freeze-account https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/accounts/{id}/freeze Freezes an account # List accounts Source: https://docs.augustus.com/api-reference/accounts/list-accounts https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/accounts Returns a paginated list of accounts. # Retrieve account Source: https://docs.augustus.com/api-reference/accounts/retrieve-account https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/accounts/{id} Retrieves an account by ID. # Retrieve account balance Source: https://docs.augustus.com/api-reference/accounts/retrieve-account-balance https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/accounts/{id}/balance Retrieves the available balance for an account. # Unfreeze account Source: https://docs.augustus.com/api-reference/accounts/unfreeze-account https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/accounts/{id}/unfreeze Unfreezes an account # Introspect current API key Source: https://docs.augustus.com/api-reference/api-key/introspect-current-api-key https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/api_key Returns the API key resource for the key authenticating this request. Useful for verifying which key is in use and discovering its current authorization context without inferring it from rejected requests. # List API versions Source: https://docs.augustus.com/api-reference/api-versions/list-api-versions https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/api_versions Returns the catalogue of publicly available Augustus Banking API versions, ordered oldest to newest. New accounts and unpinned merchants resolve to the entry with `is_latest: true`. Public: no authentication required. # List Banks Source: https://docs.augustus.com/api-reference/bank/list-banks https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/banks/list Get a list of banks. You can filter by group, capability and market. # Retrieve a Bank Source: https://docs.augustus.com/api-reference/bank/retrieve-a-bank https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/banks/details Retrieve a bank object by its id. The id is a unique identifier of the bank within Ivy. # Search a Bank Source: https://docs.augustus.com/api-reference/bank/search-a-bank https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/banks/search You can retrieve a list of banks by a given search string. If the search string is empty (""), a default list of banks is returned. On top, you can filter results by group, capability and market. # Retrieve Account Balance Source: https://docs.augustus.com/api-reference/banking/retrieve-account-balance https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/balance/retrieve Retrieve the balance of your Ivy account. The balance is the money currently available on your Ivy account. It is broken down by currency. # Retrieve your Capabilities Source: https://docs.augustus.com/api-reference/capabilities/retrieve-your-capabilities https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/merchant/capabilities/details Retrieve the capabilities of your Ivy account. The capabilities are broken down by market and by product. # Create a Checkout Session Source: https://docs.augustus.com/api-reference/checkout/create-a-checkout-session https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/checkout/session/create Creates a Checkout Session for the merchant corresponding to the given API key. See [the guide](https://docs.getivy.de/docs/payment-integration) for more information. # Expire a Checkout Session Source: https://docs.augustus.com/api-reference/checkout/expire-a-checkout-session https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/checkout/session/expire Expire a Checkout Session by Ivy id. By expiring a Checkout Session, users will not be able to access this Checkout Session anymore. # Retrieve a Checkout Session Source: https://docs.augustus.com/api-reference/checkout/retrieve-a-checkout-session https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/checkout/session/details Retrieve a Checkout Session and its details by Ivy id. # Create conversion Source: https://docs.augustus.com/api-reference/conversions/create-conversion https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/conversions Creates and executes a conversion. # List conversions Source: https://docs.augustus.com/api-reference/conversions/list-conversions https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/conversions Returns a paginated list of conversions. # Retrieve conversion Source: https://docs.augustus.com/api-reference/conversions/retrieve-conversion https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/conversions/{id} Retrieves a conversion by ID. # Create a Customer Source: https://docs.augustus.com/api-reference/customer/create-a-customer https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/customer/create Create a new Customer representing your Customers. You can use the Customer to simplify the checkout process for returning journeys. # Delete a Customer Source: https://docs.augustus.com/api-reference/customer/delete-a-customer https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/customer/delete Delete a Customer by wiping personal data and marking the customer as deleted. # Retrieve a Customer Source: https://docs.augustus.com/api-reference/customer/retrieve-a-customer https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/customer/retrieve Retrieve a Customer Object by its id. # Search Customers Source: https://docs.augustus.com/api-reference/customer/search-customers https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/customer/search Search for customers you have previously created using filters, e.g. by email. # Update a Customer Source: https://docs.augustus.com/api-reference/customer/update-a-customer https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/customer/update Update the Customer details # Retrieve a deposit Source: https://docs.augustus.com/api-reference/deposit/retrieve-a-deposit https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/deposit/retrieve Retrieves a deposit by its ID. # List deposits Source: https://docs.augustus.com/api-reference/deposits/list-deposits https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/deposits Lists deposits for the merchant with cursor-based pagination. # Retrieve deposit Source: https://docs.augustus.com/api-reference/deposits/retrieve-deposit https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/deposits/{id} Retrieves a deposit by ID. # List events Source: https://docs.augustus.com/api-reference/events/list-events https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/events Lists webhook events for the merchant with cursor-based pagination. Events are retained for 30 days. # Retrieve event Source: https://docs.augustus.com/api-reference/events/retrieve-event https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/events/{id} Retrieves a webhook event by ID. # Execute FX Source: https://docs.augustus.com/api-reference/fx/execute-fx https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/fx/execute Execute a standalone foreign exchange transaction. # Retrieve Exchange Rate Source: https://docs.augustus.com/api-reference/fx/retrieve-exchange-rate https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/fx/retrieve-rate Retrieve the current exchange rate for a given currency pair. The rate is not guaranteed for any following transactions. # Retrieve FX details Source: https://docs.augustus.com/api-reference/fx/retrieve-fx-details https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/fx/retrieve Retrieve the details of a past fx transfer using the fxId. # Create an Order Source: https://docs.augustus.com/api-reference/order/create-an-order https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/order/create Create a new order. By creating a new order, you will create a new settlement destination which you can use to settle expected incoming payments efficiently. After creating the order, Ivy provides you with a destination for the expected incoming payment. As soon as a payment with the same details arrives, Ivy will update the status of the order. # Expire an Order Source: https://docs.augustus.com/api-reference/order/expire-an-order https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/order/expire Manually expire an order before its natural expiration time. # Retrieve an Order Source: https://docs.augustus.com/api-reference/order/retrieve-an-order https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/order/details Retrieve details of an order. You can retrieve the order by passing either the internal Ivy order id or the `referenceId` you specified when creating a Checkout Session to the `id` field. # Create a payout Source: https://docs.augustus.com/api-reference/payout/create-a-payout https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/payout/create Create a payout for a merchant. # List payouts Source: https://docs.augustus.com/api-reference/payout/list-payouts https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/payout/list List payouts for a merchant. # Payout available balances Source: https://docs.augustus.com/api-reference/payout/payout-available-balances https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/beneficiary-payout/create Payout all available balances of your account to the preconfigured beneficiary bank account or wallet. If you want to handle payouts in a more dynamic and granular way, please use the POST /payout/create endpoint. # Retrieve a payout Source: https://docs.augustus.com/api-reference/payout/retrieve-a-payout https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/payout/retrieve Retrieve a payout object by id. # Create payout Source: https://docs.augustus.com/api-reference/payouts/create-payout https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/payouts Creates a new payout. # List payouts Source: https://docs.augustus.com/api-reference/payouts/list-payouts https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/payouts Lists payouts for the merchant with cursor-based pagination. # Retrieve payout Source: https://docs.augustus.com/api-reference/payouts/retrieve-payout https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/payouts/{id} Retrieves a payout by ID. # Get indicative quote Source: https://docs.augustus.com/api-reference/quotes/get-indicative-quote https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/quotes/indicative Returns an indicative quote for a currency pair. Not persisted or holdable. # Retrieve quote Source: https://docs.augustus.com/api-reference/quotes/retrieve-quote https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/quotes/{id} Retrieves a persisted quote by ID. # Create a refund Source: https://docs.augustus.com/api-reference/refund/create-a-refund https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/refund/create Creates a refund for the specified order. The order can be specified either by Ivy's internal `orderId` or by the `referenceId` provided by the merchant during checkout creation. If the refund should only be partial, you can specifiy this with the `amount` parameter. # Retrieve a refund Source: https://docs.augustus.com/api-reference/refund/retrieve-a-refund https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/refund/retrieve Returns refund details and Id of refunded order. # Create a return Source: https://docs.augustus.com/api-reference/return/create-a-return https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/return/create Creates a return for a deposit. # Retrieve a return Source: https://docs.augustus.com/api-reference/return/retrieve-a-return https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/return/retrieve Retrieves a return by its ID. # Create return Source: https://docs.augustus.com/api-reference/returns/create-return https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/returns Initiates a return of funds from a deposit to the source. # List returns Source: https://docs.augustus.com/api-reference/returns/list-returns https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/returns Lists deposit returns for the merchant with cursor-based pagination. # Retrieve return Source: https://docs.augustus.com/api-reference/returns/retrieve-return https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/returns/{id} Retrieves a return by ID. # List scopes Source: https://docs.augustus.com/api-reference/scopes/list-scopes https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/scopes Returns the catalogue of scopes available to API keys. The list is filtered by the `Api-Version` request header and defaults to the latest version when the header is omitted. Public: no authentication required. # Create a Subaccount Source: https://docs.augustus.com/api-reference/subaccount/create-a-subaccount https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/subaccount/create Create a Subaccount which can be used to reconcile orders, refunds and payouts more easily. # Retrieve a Subaccount Source: https://docs.augustus.com/api-reference/subaccount/retrieve-a-subaccount https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/subaccount/retrieve Retrieve a Subaccount by id. # List transaction history Source: https://docs.augustus.com/api-reference/transactions/list-transaction-history https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/transaction/list Retrieve a paginated list of transactions for the specified time period # List transactions Source: https://docs.augustus.com/api-reference/transactions/list-transactions https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/transactions Lists transactions for an account with cursor-based pagination. # Retrieve transaction Source: https://docs.augustus.com/api-reference/transactions/retrieve-transaction https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/transactions/{id} Retrieves a transaction by ID. # Verify payee bank account Source: https://docs.augustus.com/api-reference/vop/verify-payee-bank-account https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/payee/verify Verify that the provided account holder name matches the bank account details. **Currently supported financial address types:** - `iban`: IBAN-based accounts (EU/SEPA). It implements Verification of Payee (VoP) as required by EU Instant Payments Regulation. **Possible status values:** - `match`: Exact match - the name matches the account holder's name - `partial_match`: Close match - similar but not identical (e.g., typos, abbreviations). The `suggestedAccountHolderName` field will contain the suggested account holder name. - `no_match`: No match - the name does not match the account holder - `not_available`: Verification not possible (e.g., bank unreachable, timeout, unsupported) # List webhook deliveries Source: https://docs.augustus.com/api-reference/webhook-deliveries/list-webhook-deliveries https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/webhook_deliveries Lists webhook deliveries for the merchant with cursor-based pagination. Deliveries are retained for 30 days. # Redeliver webhook Source: https://docs.augustus.com/api-reference/webhook-deliveries/redeliver-webhook https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/webhook_deliveries/{id}/redeliver Triggers a fresh delivery attempt of the event to the same webhook subscription. # Retrieve webhook delivery Source: https://docs.augustus.com/api-reference/webhook-deliveries/retrieve-webhook-delivery https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/webhook_deliveries/{id} Retrieves a webhook delivery by ID. # account_holder.active Source: https://docs.augustus.com/api-reference/webhook-events/account_holderactive https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook account_holder.active Sent when an account holder becomes active. # account_holder.closed Source: https://docs.augustus.com/api-reference/webhook-events/account_holderclosed https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook account_holder.closed Sent when an account holder is closed. # conversion.completed Source: https://docs.augustus.com/api-reference/webhook-events/conversioncompleted https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook conversion.completed Sent when a conversion has completed successfully. # conversion.created Source: https://docs.augustus.com/api-reference/webhook-events/conversioncreated https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook conversion.created Sent when a conversion is created and processing has started. # conversion.failed Source: https://docs.augustus.com/api-reference/webhook-events/conversionfailed https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook conversion.failed Sent when a conversion has failed. # deposit.received Source: https://docs.augustus.com/api-reference/webhook-events/depositreceived https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook deposit.received Sent when a deposit is received # payout.created Source: https://docs.augustus.com/api-reference/webhook-events/payoutcreated https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook payout.created Sent when a payout is created. # payout.failed Source: https://docs.augustus.com/api-reference/webhook-events/payoutfailed https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook payout.failed Sent when a payout has failed. # payout.initiated Source: https://docs.augustus.com/api-reference/webhook-events/payoutinitiated https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook payout.initiated Sent when a payout is initiated and processing has started. # payout.paid Source: https://docs.augustus.com/api-reference/webhook-events/payoutpaid https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook payout.paid Sent when a payout has been successfully delivered. # ping.test Source: https://docs.augustus.com/api-reference/webhook-events/pingtest https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook ping.test Sent when a merchant explicitly triggers a test delivery to one of their webhook subscriptions. Does not reflect any real business activity; handlers should short-circuit on this event type. # return.failed Source: https://docs.augustus.com/api-reference/webhook-events/returnfailed https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook return.failed Sent when a deposit return has failed. # return.initiated Source: https://docs.augustus.com/api-reference/webhook-events/returninitiated https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook return.initiated Sent when a deposit return has been initiated. # return.paid Source: https://docs.augustus.com/api-reference/webhook-events/returnpaid https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook return.paid Sent when a deposit return outbound payment has been paid. # return.returned Source: https://docs.augustus.com/api-reference/webhook-events/returnreturned https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml webhook return.returned Sent when a succeeded deposit return was reversed or returned. # Create a webhook subscription Source: https://docs.augustus.com/api-reference/webhook-subscription/create-a-webhook-subscription https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/webhook-subscription/create Creates a webhook subscription that sends various events from Ivy to a specified url. There can be multiple subscriptions per app. # Delete a webhook subscription Source: https://docs.augustus.com/api-reference/webhook-subscription/delete-a-webhook-subscription https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/webhook-subscription/delete Deletes a webhook subscription. # List webhook subscriptions Source: https://docs.augustus.com/api-reference/webhook-subscription/list-webhook-subscriptions https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/webhook-subscription/list Lists all webhook subscriptions that are registered for the merchant. The results are paginated and provided in chronological order. # Ping a webhook subscription Source: https://docs.augustus.com/api-reference/webhook-subscription/ping-a-webhook-subscription https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/webhook-subscription/ping Sends a test ping to verify webhook subscription endpoint connectivity. # Update a webhook subscription Source: https://docs.augustus.com/api-reference/webhook-subscription/update-a-webhook-subscription https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/webhook-subscription/update Updates the url or subcribed to events for a webhook subscription. This can be used via the app or via the API by providing an API key. # Create webhook subscription Source: https://docs.augustus.com/api-reference/webhook-subscriptions/create-webhook-subscription https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/webhook_subscriptions Creates a new webhook subscription. # Delete webhook subscription Source: https://docs.augustus.com/api-reference/webhook-subscriptions/delete-webhook-subscription https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml delete /v1/webhook_subscriptions/{id} Permanently deletes a webhook subscription. This cannot be undone. # List webhook subscriptions Source: https://docs.augustus.com/api-reference/webhook-subscriptions/list-webhook-subscriptions https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/webhook_subscriptions Lists webhook subscriptions for the merchant with cursor-based pagination. # Retrieve webhook subscription Source: https://docs.augustus.com/api-reference/webhook-subscriptions/retrieve-webhook-subscription https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml get /v1/webhook_subscriptions/{id} Retrieves a webhook subscription by ID. # Send test event Source: https://docs.augustus.com/api-reference/webhook-subscriptions/send-test-event https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/webhook_subscriptions/{id}/send_test_event Dispatches a signed `ping.test` event to this subscription's URL through the same pipeline as real events. Useful for verifying your receiver's reachability and signature verification in any environment without creating a real business event. Test-event failures do not affect the subscription's health counters or trigger failure-notification emails. # Update webhook subscription Source: https://docs.augustus.com/api-reference/webhook-subscriptions/update-webhook-subscription https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml post /v1/webhook_subscriptions/{id} Updates the URL and/or subscribed events. # Trigger a specific webhook Source: https://docs.augustus.com/api-reference/webhook/trigger-a-specific-webhook https://app.stainless.com/api/spec/documented/getivy/openapi.documented.yml post /api/service/webhook/trigger This endpoint allows you to trigger a specific webhook by its ID. # checkout_session_completed Source: https://docs.augustus.com/api-reference/webhookeventexamples/checkout_session_completed https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/checkout_session_completed A checkout session has been completed # checkout_session_created Source: https://docs.augustus.com/api-reference/webhookeventexamples/checkout_session_created https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/checkout_session_created A checkout session has been created # checkout_session_expired Source: https://docs.augustus.com/api-reference/webhookeventexamples/checkout_session_expired https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/checkout_session_expired A checkout session has expired # checkout_session_updated Source: https://docs.augustus.com/api-reference/webhookeventexamples/checkout_session_updated https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/checkout_session_updated A checkout session has been updated # data_session_completed Source: https://docs.augustus.com/api-reference/webhookeventexamples/data_session_completed https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/data_session_completed A data session has been completed # deposit.received Source: https://docs.augustus.com/api-reference/webhookeventexamples/depositreceived https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/deposit.received A deposit has been received # fx.failed Source: https://docs.augustus.com/api-reference/webhookeventexamples/fxfailed https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/fx.failed An FX has failed # fx.initiated Source: https://docs.augustus.com/api-reference/webhookeventexamples/fxinitiated https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/fx.initiated An FX has been initiated # fx.succeeded Source: https://docs.augustus.com/api-reference/webhookeventexamples/fxsucceeded https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/fx.succeeded An FX has succeeded # merchant_updated Source: https://docs.augustus.com/api-reference/webhookeventexamples/merchant_updated https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/merchant_updated Your merchant account has been updated # order_created Source: https://docs.augustus.com/api-reference/webhookeventexamples/order_created https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/order_created An order has been created # order_updated Source: https://docs.augustus.com/api-reference/webhookeventexamples/order_updated https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/order_updated An order has been updated # payout_created Source: https://docs.augustus.com/api-reference/webhookeventexamples/payout_created https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/payout_created A payout has been created # payout_report_requested Source: https://docs.augustus.com/api-reference/webhookeventexamples/payout_report_requested https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/payout_report_requested A payout report has been requested # payout_updated Source: https://docs.augustus.com/api-reference/webhookeventexamples/payout_updated https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/payout_updated A payout has been updated # payout.failed Source: https://docs.augustus.com/api-reference/webhookeventexamples/payoutfailed https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/payout.failed A payout has failed # payout.initiated Source: https://docs.augustus.com/api-reference/webhookeventexamples/payoutinitiated https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/payout.initiated A payout has been initiated # payout.paid Source: https://docs.augustus.com/api-reference/webhookeventexamples/payoutpaid https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/payout.paid A payout has been paid # refund_failed Source: https://docs.augustus.com/api-reference/webhookeventexamples/refund_failed https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/refund_failed A refund initiated with `/merchant/payment/refund` failed # refund_succeeded Source: https://docs.augustus.com/api-reference/webhookeventexamples/refund_succeeded https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/refund_succeeded A refund initiated with `/merchant/payment/refund` succeeded # refund.failed Source: https://docs.augustus.com/api-reference/webhookeventexamples/refundfailed https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/refund.failed A refund initiated with `/refund/create` failed # refund.initiated Source: https://docs.augustus.com/api-reference/webhookeventexamples/refundinitiated https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/refund.initiated A refund initiated with `/refund/create` # refund.succeeded Source: https://docs.augustus.com/api-reference/webhookeventexamples/refundsucceeded https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/refund.succeeded A refund initiated with `/refund/create` succeeded # return.failed Source: https://docs.augustus.com/api-reference/webhookeventexamples/returnfailed https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/return.failed A return has failed # return.initiated Source: https://docs.augustus.com/api-reference/webhookeventexamples/returninitiated https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/return.initiated A return has been initiated # return.returned Source: https://docs.augustus.com/api-reference/webhookeventexamples/returnreturned https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/return.returned A return has been returned # return.succeeded Source: https://docs.augustus.com/api-reference/webhookeventexamples/returnsucceeded https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/return.succeeded A return has succeeded # Test Source: https://docs.augustus.com/api-reference/webhookeventexamples/test https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/test Can be triggered with `/webhook-subscription/ping` to test the integration # user_payout.failed Source: https://docs.augustus.com/api-reference/webhookeventexamples/user_payoutfailed https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/user_payout.failed A customer payout has failed # user_payout.initiated Source: https://docs.augustus.com/api-reference/webhookeventexamples/user_payoutinitiated https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/user_payout.initiated A customer payout has been initiated # user_payout.paid Source: https://docs.augustus.com/api-reference/webhookeventexamples/user_payoutpaid https://api.getivy.de/openapi/webhooks/json post /api/service/webhook-event/user_payout.paid A customer payout has been paid # Off-ramp Source: https://docs.augustus.com/docs/On-Offramp/offramp Deposit crypto funds to your Augustus wallet and off-ramp to fiat to fund your fiat operations Convert USDC into fiat and pay it out to a bank account in two steps: 1. Create a conversion. 2. Create a payout. ## Supported currencies * **Stablecoins:** USDC on Ethereum, Solana, Polygon. * **Fiat:** EUR, GBP, USD. Minimum off-ramp amount: 10 units of source currency. ## Steps Account IDs are shown in the Dashboard under **Accounts → Details**. Find your chain and address in the Dashboard under **Accounts → select wallet account → Linked wallets**. Send USDC only from a [linked wallet](/docs/accounts/wallets#linked-wallets). ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const balance = await client.accounts.retrieveBalance('your-usdc-account-id') ``` [**GET** `/v1/accounts/{id}/balance` in the API Reference →](/api-reference/accounts/retrieve-account-balance) ```ts theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const balance = await client.balance.retrieve({ currency: 'USDC' }) ``` [**POST** `/api/service/balance/retrieve` in the API Reference →](/api-reference/banking/retrieve-account-balance) ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const quote = await client.quotes.indicative.retrieve({ source_currency: 'USDC', target_currency: 'EUR', source_amount: '100', }) ``` [**GET** `/v1/quotes/indicative` in the API Reference →](/api-reference/quotes/get-indicative-quote) ```ts theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const rate = await client.fx.retrieveRate({ sourceCurrency: 'USDC', targetCurrency: 'EUR', sourceAmount: '100', }) ``` [**POST** `/api/service/fx/retrieve-rate` in the API Reference →](/api-reference/fx/retrieve-exchange-rate) ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const conversion = await client.conversions.create({ source_account_id: 'your-usdc-account-id', target_account_id: 'your-eur-account-id', source_amount: '100', }) ``` [**POST** `/v1/conversions` in the API Reference →](/api-reference/conversions/create-conversion) ```ts theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const fx = await client.fx.execute({ sourceAccountId: 'your-usdc-account-id', targetAccountId: 'your-eur-account-id', sourceAmount: '100', }) ``` [**POST** `/api/service/fx/execute` in the API Reference →](/api-reference/fx/execute-fx) Conversions are asynchronous. Poll or subscribe to webhooks. ```ts theme={null} const result = await client.conversions.retrieve(conversionId) if (result.status !== 'completed') { // still pending or failed } ``` [**GET** `/v1/conversions/{id}` in the API Reference →](/api-reference/conversions/retrieve-conversion) ```ts theme={null} const fx = await client.fx.retrieve({ fxId }) if (fx.status !== 'succeeded') { // still initiated or failed } ``` [**POST** `/api/service/fx/retrieve` in the API Reference →](/api-reference/fx/retrieve-fx-details) ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const payout = await client.payouts.create({ source_account_id: 'your-eur-account-id', amount: '100', currency: 'EUR', reference: 'Off-ramp payout', destination: { type: 'iban', iban: 'DE89370400440532013000', account_holder_name: 'Acme Ltd', }, }) ``` [**POST** `/v1/payouts` in the API Reference →](/api-reference/payouts/create-payout) ```ts theme={null} 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: { accountHolderName: 'Acme Ltd', iban: 'DE89370400440532013000', }, }, }, }) ``` [**POST** `/api/service/payout` in the API Reference →](/api-reference/payout/create-a-payout) Monitor in the Dashboard or via webhooks. Funds usually arrive within minutes. Delivery can take up to 2 business days depending on the receiving bank. # On-ramp Source: https://docs.augustus.com/docs/On-Offramp/onramp On-ramp fiat funds to USDC to fund your crypto operations Convert your fiat balance into USDC and send it to a linked external wallet in two steps: 1. Create a conversion. 2. Create a payout. ## Supported currencies * **Fiat:** EUR, GBP, USD. * **Stablecoins:** USDC (Ethereum, Solana, Polygon), USDT (soon). Minimum on-ramp amount: 10 units of source currency. ## Fund your account first Fund via [Deposits](/docs/payin/deposits), [Open Banking](/docs/payin/instant-bank-transfer/payment-integration), or [Manual Bank Transfer](/docs/payin/mbt/mbt). ## Steps Account IDs are shown in the Dashboard under **Accounts → Details**. ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const balance = await client.accounts.retrieveBalance('your-eur-account-id') ``` [**GET** `/v1/accounts/{id}/balance` in the API Reference →](/api-reference/accounts/retrieve-account-balance) ```ts theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const balance = await client.balance.retrieve({ currency: 'EUR' }) ``` [**POST** `/api/service/balance/retrieve` in the API Reference →](/api-reference/banking/retrieve-account-balance) ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const quote = await client.quotes.indicative.retrieve({ source_currency: 'EUR', target_currency: 'USDC', source_amount: '100', }) ``` [**GET** `/v1/quotes/indicative` in the API Reference →](/api-reference/quotes/get-indicative-quote) ```ts theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const rate = await client.fx.retrieveRate({ sourceCurrency: 'EUR', targetCurrency: 'USDC', sourceAmount: '100', }) ``` [**POST** `/api/service/fx/retrieve-rate` in the API Reference →](/api-reference/fx/retrieve-exchange-rate) Get `source_account_id` and `target_account_id` for the accounts you want to use from the **Accounts** tab in the Dashboard. ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const conversion = await client.conversions.create({ source_account_id: 'your-eur-account-id', target_account_id: 'your-usdc-account-id', source_amount: '100', }) ``` [**POST** `/v1/conversions` in the API Reference →](/api-reference/conversions/create-conversion) ```ts theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const fx = await client.fx.execute({ sourceAccountId: 'your-eur-account-id', targetAccountId: 'your-usdc-account-id', sourceAmount: '100', }) ``` [**POST** `/api/service/fx/execute` in the API Reference →](/api-reference/fx/execute-fx) Conversions are asynchronous. Poll or subscribe to webhooks. ```ts theme={null} const result = await client.conversions.retrieve(conversionId) if (result.status !== 'completed') { // still pending or failed } ``` [**GET** `/v1/conversions/{id}` in the API Reference →](/api-reference/conversions/retrieve-conversion) ```ts theme={null} const fx = await client.fx.retrieve({ fxId }) if (fx.status !== 'succeeded') { // still initiated or failed } ``` [**POST** `/api/service/fx/retrieve` in the API Reference →](/api-reference/fx/retrieve-fx-details) ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const payout = await client.payouts.create({ source_account_id: 'your-usdc-account-id', amount: '100', currency: 'USDC', reference: 'On-ramp payout', destination: { type: 'crypto_wallet', address: 'YourSolanaWalletAddress', blockchain: 'solana', }, }) ``` [**POST** `/v1/payouts` in the API Reference →](/api-reference/payouts/create-payout) ```ts theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const payout = await client.payouts.create({ amount: 100, currency: 'USDC', destination: { type: 'beneficiary', financialAddress: { type: 'wallet', wallet: { address: 'YourSolanaWalletAddress', blockchain: 'SOL' }, }, }, }) ``` [**POST** `/api/service/payout` in the API Reference →](/api-reference/payout/create-a-payout) Monitor in the Dashboard or via webhooks. Funds usually arrive within minutes. Finalization on Ethereum can take up to 20 minutes. # Balances Source: https://docs.augustus.com/docs/accounts/balances Hold fiat and stablecoin funds in your Augustus account Manage multiple currency accounts in one place. Each currency has its own account with the appropriate payment details for that rail (e.g. IBAN for EUR, sort code and account number for GBP, ABA routing number and account number for USD, wallet address for [stablecoin wallets](/docs/accounts/wallets)). ## Balance types * **Available** — funds you can use for payouts and refunds. * **Pending** — funds still clearing (e.g. recent deposits or in-flight payouts). ## Retrieve a balance ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const balance = await client.accounts.retrieveBalance('your-eur-account-id') ``` Find each Account ID in the Dashboard under **Accounts → Details**. [**GET** `/v1/accounts/{id}/balance` in the API Reference →](/api-reference/accounts/retrieve-account-balance) ```ts theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const balance = await client.balance.retrieve({ currency: 'EUR' }) ``` Find each Account ID in the Dashboard under **Accounts → Details**. [**POST** `/api/service/balance/retrieve` in the API Reference →](/api-reference/banking/retrieve-account-balance) ## Supported currencies * **Fiat:** EUR, GBP, USD. * **Stablecoins:** USDC on Ethereum, Solana, Polygon. See [Wallets](/docs/accounts/wallets). # Overview Source: https://docs.augustus.com/docs/accounts/overview Create, manage, and track accounts at Augustus. Hold balances and track transactions across multiple currencies, and manage them via API or the Dashboard. Fiat accounts with rail-specific payment details (FBO and DDA accounts) Hold USDC balances in your Augustus custodial wallet. Track and generate reports for all money movements on your accounts. Convert between fiat and stablecoin across USD, EUR, GBP, USDC. Sub-ledgered accounts with payment details in your customer's name. Send and receive on their behalf. # Reports Source: https://docs.augustus.com/docs/accounts/reports Generate account statements and transaction reports for reconciliation, accounting, and audit. Augustus provides three ways to retrieve account activity for reconciliation, accounting, and audit. ## Output types JSON ledger of credits and debits for an account, via the API CSV of all transactions for an account, via the dashboard PDF statement for an account, downloaded via the dashboard ## Transactions list (API, JSON) Fetch the ledger of credits and debits on an account in JSON format. Use it for programmatic reconciliation, custom reporting, and building balance time series. ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() for await (const transaction of client.transactions.list({ account_id: 'your-account-id', created_at: { gte: '2024-07-11T00:00:00Z', lte: '2024-07-12T00:00:00Z' }, })) { // process transaction } ``` [**GET** `/v1/transactions` in the API Reference →](/api-reference/transactions/list-transactions) ```ts theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() let afterCursor: string | undefined do { const page = await client.transactions.list({ accountId: 'your-account-id', from: 1720656000, to: 1720742400, afterCursor, }) for (const transaction of page.data) { // process transaction } afterCursor = page.paging.nextCursor } while (afterCursor) ``` [**POST** `/api/service/transaction/list` in the API Reference →](/api-reference/transactions/list-transaction-history) ### Point-in-time balances Each transaction includes the account balance immediately **before** and **after** the movement. Use these to reconstruct balances at any point in time: * For the balance at midnight yesterday, fetch the first transaction after that time and read its `before` balance. * For a balance chart, stitch `after` balances over time. For the current balance, use [Balances](/docs/accounts/balances) instead. ### Transaction date The transaction date is when the movement is recorded on the Augustus ledger. For credits, this is when funds settled. For debits, this is when the payout was initiated. ## Transaction report (Dashboard, CSV) The transaction report is a CSV export of all transactions for a single account over a selected period. Use it for spreadsheet-based reconciliation and finance workflows. [**POST** `/api/service/transaction/list` in the API Reference →](/api-reference/transactions/list-transactions) Each row represents a money movement including amount, direction, counterparty, related resource (deposit, payout, return, conversion), and timestamps. Download from the [Augustus Dashboard](https://dashboard.augustus.com) under **Accounts → Account details → Statement → Transaction report**. ## Account statement (Dashboard, PDF) An account statement is a PDF scoped to a single account and currency, suitable for audit and third-party sharing. Download one per account you want to reconcile: * **EUR** — operating account statement in EUR, covering IBAN-based deposits, payouts, and returns. * **GBP** — operating account statement in GBP, covering Faster Payments, CHAPS, and sort code / account number activity. * **USD** — operating account statement in USD, covering ACH, Fedwire, and ABA-based activity. * **USDC** — stablecoin wallet statement, covering on-chain deposits and payouts across supported chains (Ethereum, Solana, Polygon). Each statement includes: * Opening and closing balance for the reporting period. * Every credit and debit with timestamp, counterparty, and reference. Download from the [Augustus Dashboard](https://dashboard.augustus.com) under **Accounts → Account details → Statement**. Reports and statements reflect settled activity. Pending transactions appear once they settle. See [Balances](/docs/accounts/balances) for real-time available and pending balances. # Virtual accounts (FBO) Source: https://docs.augustus.com/docs/accounts/virtual-accounts Sub-ledgered balances with unique account identifiers, under a bank account you hold with Augustus. *Virtual Accounts are in beta. Contact [will@augustus.com](mailto:will@augustus.com) to enable them on your account.* Virtual Accounts are sub-ledgered balances with unique account identifiers, sitting under a bank account you hold with Augustus. They give you the infrastructure to implement per-customer accounts on your platform, with automated reconciliation and the ability to send and receive payments in your customers' names. The primary use case is **FBO with Virtual Accounts**: you open a client-funds account with Augustus For Benefit Of (FBO) your customers, then provision a Virtual Account inside it for each of your end-users. This guide explains how that works and how to integrate it. *** ## FBO with Virtual Accounts You open a single FBO account at Augustus in your name, *for the benefit of* your customers. Under the FBO Program, you create one Virtual Account per end-user. Each Virtual Account has: * A unique 12-digit US account number reachable over ACH, FedWire, and FedNow. * Its own sub-ledger and balance. * The end-user's name for sending and receiving payments — Collection-on-Behalf-of (CoBo) and Payment-on-Behalf-of (PoBo). This gives you per-user accounting and named payments without needing a separate bank account for every customer. Funds remain in your single FBO account; sub-ledgering and naming sit on top. ```mermaid theme={null} flowchart LR M[Your business] --> AP[Account Program
FBO master account
USD] AP --> VA1[Virtual Account
End-user A] AP --> VA2[Virtual Account
End-user B] AP --> VA3[Virtual Account
End-user C] ``` ### Two primitives **Account Program.** Your master FBO account at Augustus, held in your name *for the benefit of* your customers. From your perspective this is one account; sub-ledgering and named payments are layered on top. One currency per Program — a setup needing both USD and EUR uses two Programs. **Sponsored vs. unsponsored Programs.** Two Account Program variants exist (`Program Managed` and `Sponsored`). The right variant depends on your licensing and use case. Talk to your account manager to confirm which is suitable. **Virtual Account.** A sub-ledgered balance under your Account Program with its own 12-digit US account number. Created by you via API once the end-user's beneficiary data is collected. Used to receive funds in and send funds out in the name of a single end-user. *** ## Status model Accounts and Programs share the same status model. | Status | Behavior | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pending` | Newly opened, not yet activated. Augustus typically activates within minutes. Some accounts require additional information (e.g. enhanced due diligence) before activation. | | `active` | Normal. Pay-ins and pay-outs allowed. | | `frozen` | No pay-ins or pay-outs. Reversible — call `/unfreeze` to return to `active`. | | `closed` | Terminal. The account must be `frozen` first, then closed. **Cannot be reopened** — open a new Virtual Account if the holder needs an account again. | Cascade rules: * Freezing a Program freezes every account inside it. * Closing a Program requires every account inside it to already be empty or closed. * Account-level status changes never propagate up to the Program. *** ## Beneficiary data: what you provide for each Virtual Account To open a Virtual Account, send Augustus the beneficiary data for the end-user. Required CIP fields differ by beneficiary type. * Legal name * Residential address * Date of birth * Identification: SSN, ITIN, or government ID number * Country of citizenship * Legal business name * DBA (if applicable) * Registered address * Physical address * Registration number (EIN / TIN) * Year of incorporation * State of incorporation * Country of incorporation (if non-US) Open at most one Virtual Account per entity under each Account Program. *** ## Money in: receiving funds Each Virtual Account has its own routable account number, so funds arriving over US rails settle directly into the right Virtual Account without you doing any routing. | Rail | Speed | Use case | | --------------- | ------------------- | ------------------------------------------- | | **ACH** | 1–3 business days | Low-cost retail flows | | **FedWire** | Same-day | High-value or business-hours wires | | **FedNow** | Real-time, 24/7/365 | Instant funding | | **SWIFT (USD)** | Same/next-day | International USD inbound to your end-users | When a credit arrives, Augustus matches the destination account number to a Virtual Account, performs sanctions and AML screening, and credits the Virtual Account's balance. You receive a webhook on the Virtual Account. If a credit can't be matched (wrong account number, sanctions hit, frozen account), Augustus returns it via the originating rail and notifies you with the reason. *** ## Money out: sending funds You initiate pay-outs *from a Virtual Account* — the source account is the Virtual Account. The end-user's name appears as the originator on the rail, known as **Pay-on-Behalf-of (PoBo)**. The Virtual Account holder's name appears to the receiving bank and beneficiary. Funds are debited from the Virtual Account atomically at payout initiation. Payout request and response shapes follow the existing [Payouts API](/docs/payout/payout) — the only addition is that the source account is a Virtual Account. *** ## Integration The endpoints below show the shape of the API and the key calls you'll make to integrate Virtual Accounts. The full reference, including all status-change endpoints, lives in the API reference. All Account and Account Program endpoints sit under the `v1/accounts/*` and `v1/account-programs/*` namespaces. They follow the same auth, error, and pagination conventions as the rest of the [2026-05-01 API](/v1/introduction). **Sandbox.** All Virtual Account flows are available in test mode with simulated rail movements. See [Test Mode](/docs/basics/test-mode-sandbox). ### Open a Virtual Account ```ts 2026-05-01 theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const account = await client.accounts.create({ account_program_id: 'ap_01HABC...', account_type: 'virtual_account', beneficiary_data: { legal_name: 'Jane Doe', date_of_birth: '1990-04-12', country_of_citizenship: 'US', identification: { type: 'ssn', value: '***-**-1234' }, residential_address: { street_line_1: '123 Market St', city: 'San Francisco', state: 'CA', postal_code: '94105', country: 'US', }, }, }) ``` The Virtual Account opens in `pending` and is activated by Augustus once verification clears, usually within minutes. If additional information is required (EDD, sanctions hit, or identity mismatch), the Virtual Account stays `pending` and Augustus contacts you with next steps. ### List accounts With no `parent_id`, returns accounts owned directly by your business entity. With `parent_id`, returns the Virtual Accounts under that Account Program. ```ts 2026-05-01 theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() for await (const account of client.accounts.list({ parent_id: 'ap_01HABC...', })) { // process account } ``` ### Get an account balance ```ts 2026-05-01 theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const balance = await client.accounts.retrieveBalance('acc_01HXYZ...') console.log(balance) // { // type: 'account_balance', // account_id: 'acc_01HXYZ...', // amount: '5230.55', // currency: 'USD', // as_of: '2026-09-15T14:32:00Z', // } ``` # Wallets Source: https://docs.augustus.com/docs/accounts/wallets Enable Crypto Wallets and find wallet information for stablecoin payments ## Set up a wallet Contact your Augustus account manager to enable wallets for stablecoin flows. Once enabled, find the wallet blockchain, address, linked wallets, and account ID in the Dashboard under **Accounts**. ## Supported currencies * **USDC** (Ethereum, Solana, Polygon) * **USDT** (soon) Augustus wallets are separated by chain. Deposits and payouts are restricted to linked external addresses. ## Linked wallets A **linked wallet** is an external wallet address that you have confirmed ownership of and verified with Augustus. Deposits into your Augustus wallet and payouts from it are restricted to your linked wallets — funds sent from any other address are rejected. Augustus supports closed-loop payments and deposits from linked wallets owned by the merchant. Contact your account manager to link the wallets you want to use for stablecoin deposits and payouts. # Core concepts Source: https://docs.augustus.com/docs/basics/concepts The capabilities Augustus offers: accepting payments, sending payouts, holding balances, converting currencies, and more. Augustus exposes money movement as a small set of API resources. Combine them for your use case. Most work identically for fiat and stablecoins. Where a feature is specific to one API, it's marked *(2026-05-01)* or *(2023-01-01)* below. ## Accounts and balances * **Operating accounts** — hold fiat balances (EUR, GBP, USD). Each has payment details for its rail (IBAN, sort code, ABA). [Learn more](/docs/accounts/overview). * **Stablecoin wallets** — hold USDC on Ethereum, Solana, or Polygon. [Learn more](/docs/accounts/wallets). * **Virtual accounts** — sub-ledgered accounts with payment details in your customer's name. [Learn more](/docs/accounts/virtual-accounts). * **Balances** — available and pending funds per account. [Learn more](/docs/accounts/balances). * **Transactions** — ledger of every credit and debit. [Learn more](/docs/accounts/reports). ## Deposits and returns * **Deposits** — funds arriving on an account's payment details. Reconciled automatically. [Learn more](/docs/payin/deposits). * **Returns** — send a deposit back to its original sender. The 2026-05-01 API auto-initiates returns for unmatched deposits. [Learn more](/docs/payin/deposits#returns). * **Open Banking Checkout** *(2023-01-01)* — instant bank checkout. [Learn more](/docs/payin/instant-bank-transfer/payment-integration). * **Manual Bank Transfer** *(2023-01-01)* — the customer sends funds using payment details you display. [Learn more](/docs/payin/mbt/mbt). ## Payouts * **Payouts** — send fiat or stablecoins to a bank account or wallet. [Learn more](/docs/payout/payout). * **International payouts** *(2026-05-01)* — send USD worldwide with routing, validation, and tracking. [Learn more](/docs/payout/international-payouts). * **Refunds** *(2023-01-01)* — return a previous Open Banking or Manual Bank Transfer payment. Full or partial. [Learn more](/docs/payout/refunds-payouts). ## Conversions Convert between currencies on demand. * Fiat ↔ stablecoin for on-ramp / off-ramp. [Learn more](/docs/On-Offramp/onramp). * Fiat ↔ fiat for cross-border flows (coming soon). * Stablecoin ↔ stablecoin for treasury (coming soon). ## Webhooks Subscribe to events for real-time notifications on deposits, payouts, orders, and more. Verify the signature and process the event. * 2026-05-01: [Webhooks](/v1/webhooks). * 2023-01-01: [Webhooks](/webhook-getting-started/introduction). ## Rate limits Each source IP can send up to **10,000 requests per 5-minute window** across all endpoints. Requests that exceed this limit return `429 Too Many Requests`. # Dashboard Source: https://docs.augustus.com/docs/basics/dashboard Learn the basics of the Augustus Dashboard. The Augustus Dashboard is where you manage accounts, invite team members, configure your integration, and monitor activity. ## Features A sandbox for testing all endpoints and webhooks without moving real money.
See [Test Mode](/docs/basics/test-mode-sandbox). View all accounts (fiat accounts or stablecoin wallets) and their balances, available currencies, capabilities, account numbers (IBAN, sort code, ABA, or wallet address), and Account IDs. Search and view all inbound and outbound payment types, plus granular transaction information and status on your Augustus account. Filter transactions by date, status, payment method, or market. Save frequent filters and combine them. Search and view all past conversions between fiat and stablecoins, and their status. View and monitor accrued interest, collateral value, and transactions for your loans. View and export payments, payouts, refunds, deposits, and transactions in CSV or Excel. Adjust account information, including team members and money movement settings. Invite team members with role-based access. Audit logs track member activity. For Open Banking checkout, configure which countries and banks appear to customers, set currency preferences, and enable payment methods per region. Create and edit developer settings, including API keys, secrets, and webhooks. Register endpoints and subscribe to events for real-time updates on deposits, payouts, orders, and more. Webhook setup requires step-up 2FA and an Admin or Owner role. * **Test keys** — for the sandbox. * **Live keys** — for production. Manage under **API Settings**. Only Owners and Admins can create, roll, revoke, or delete keys. ## Roles and permissions Each team member has one of five roles: * **Owner** — full access, including promoting other users to Owner. * **Admin** — manage team members, API keys, and payment settings. Cannot remove Owners or other Admins. * **Editor** — for developers managing the integration, webhooks, and technical configuration. * **Operator** — for support and operations. Can execute refunds and simulate test flows. * **Viewer** — read-only. ### Detailed permissions **Can:** * View all data * Invite, promote, and demote users at any role (except other Owners) * Remove users (including Admins) * Execute refunds * Manage API keys (create, roll, revoke, delete) * Manage payment settings **Cannot:** * Demote themselves * Remove the last Owner **Can:** * View all data * Invite users up to Admin * Promote users up to Admin * Demote users from Editor to Viewer * Execute refunds * Manage API keys (create, roll, revoke, delete) * Manage payment settings **Cannot:** * Demote themselves * Demote an Owner or another Admin **Can:** * View all data * Execute refunds * Configure webhook subscriptions and send test webhooks * Access integration settings **Cannot:** * Invite, promote, or demote users * Adjust payment settings **Can:** * View all data * Execute refunds * Simulate test payments and refunds **Cannot:** * Invite, promote, or demote users * Adjust payment settings **Can:** * View all data **Cannot:** * Invite, promote, or demote users * Move money or adjust payment settings ## Two-factor authentication Dashboard login uses Strong Customer Authentication via biometrics (recommended) or TOTP. Sensitive actions trigger step-up 2FA: * API key generation * Webhook settings * Money movements * Dashboard settings Contact your account manager for more information. # Welcome to Augustus Source: https://docs.augustus.com/docs/basics/introduction About Augustus and how to get up and running fast. Augustus is an OCC-licensed clearing bank (in organization) built for developers. Open accounts, hold balances, receive deposits, send payouts, and convert between fiat and stablecoins — all through one API. Hold fiat and stablecoin balances. Each account has its own payment details. Deposit funds directly to your Augustus account (IBAN, sort code, ABA, wallet). Send funds locally and globally to accounts or wallets. Convert between fiat and stablecoin held in your Augustus account Generate account & transaction reports for all money movements (CSV/PDF) Collect funds via Open Banking from your customers (`2023-01-01` only). **Two APIs at Augustus** * `2023-01-01 (prev. Ivy)`— Open Banking and Manual Bank Transfer.
SDK: `@getivy/node-sdk` * `2026-05-01` — the banking API (accounts, deposits, payouts, virtual accounts, conversions). SDK: `@augustusbank/typescript-sdk` Where a feature exists in both, code samples appear in dual-tab blocks. Otherwise the code sample uses the API that supports it. ## Get started Map your company's treasury and payment flows to our [product features](/docs/basics/concepts). [Request sandbox access](https://dashboard.augustus.com/sign-up). Signup is currently invite-only during our launch window. Toggle [Test Mode](/docs/basics/test-mode-sandbox) to get test API keys and start testing in a sandbox. Generate API keys, register webhook endpoints, and invite team members. Complete KYB and integration review. Augustus activates your account for live processing. Switch to your live API keys and monitor activity via webhooks and the Dashboard. Questions? Reach out at [help@augustus.com](mailto:help@augustus.com). # Test mode Source: https://docs.augustus.com/docs/basics/test-mode-sandbox Use Test Mode to test your Augustus integration before going live with payments. Test Mode gives you test API keys and a sandbox where you can simulate deposits, payouts, refunds, and orders without moving real money. Augustus Sandbox Mode Test Transaction ## Use Test Mode Toggle **Test Mode** in the user menu of the Dashboard. Test Mode Selector Find and generate your test API key under **Developer → Secrets**. Use it with the sandbox base URL — see the API reference for URLs. Simulate a deposit in the Dashboard under **Payments → Deposits → \[+ Create deposit]** to trigger test payments in the desired account.

*Ensure you have turned off auto-returns under **Settings → Money** for payments to arrive in your account.* Once your account is activated, switch off Test Mode and generate live API keys. The Test Mode toggle in the Dashboard does not affect your integration. Your API keys and base URL determine which mode you're in. ## Test a payout Use any destination. Open the payout in its detail view. Toggle success or failure. Verify status and webhooks. Sandbox tools for simulating payout flows ## Simulate outgoing transactions manually Under the **Simulations** tab in the Developer section, create outgoing transactions with any amount, external reference, and status. ## Test a return Initiate a return via API or manually from the Augustus Dashboard. Find the deposit and open its detail view to access Sandbox Tools. Deposit Return Screenshot ## Production Switch to live API keys and start with small amounts. ## What's next * Sandbox base URLs: [2026-05-01](/v1/introduction) / [2023-01-01](/reference/introduction). * Webhooks: [2026-05-01](/v1/webhooks) / [2023-01-01](/webhook-getting-started/introduction). * [Test your Open Banking integration](/docs/payin/instant-bank-transfer/test-your-integration) (2023-01-01 users only). # Loans Source: https://docs.augustus.com/docs/loans/loans Streamline liquidity management with access to credit direct to your DDA Augustus offers credit to institutional clients, secured by assets you already hold: incoming payments and invoices, or digital assets in qualified custody. Loans settle entirely through your existing Augustus accounts — disbursements credit your USD Operating Account (DDA), and repayments are debited from your nominated DDA. 1. **Working Capital Loans** — committed credit lines against your invoices and incoming payments. 2. **Margin Loans** — borrow USD against your bitcoin and digital assets. Loans are available to institutional clients and subject to underwriting. Thresholds, rates, advance rates, and cure windows are set in your loan agreement. ## Working Capital Loans A committed credit line against your eligible invoices or incoming payments — draw when you need it, without waiting for pending transactions to settle. Augustus reviews your receivables and commits a credit line with an advance rate against eligible collateral. Your available capacity updates as invoices and incoming payments are verified. Request a draw against your available capacity. Funds are credited to your Augustus DDA, ready for [payouts](/docs/payout/payout) or internal transfers. Inbound transactions repay drawn balances instantly, reducing operational overhead and minimising financing costs. ## Margin Loans Borrow USD against digital asset collateral held in qualified custody with Augustus. Collateral is segregated and never rehypothecated. Transfer digital assets to your dedicated collateral account at Augustus — a segregated account under your profile with its own deposit address, separate from your operating wallets. Once collateral is confirmed, USD is disbursed to your Augustus DDA and available for use. Track your loan-to-value ratio (LTV), outstanding balance, and accrued interest in the Dashboard. Top up collateral or request a release of excess collateral instantly. Interest accrues daily and is collected monthly from your nominated DDA. All remaining collateral is released upon repayment of the facility. If your LTV rises above the margin-call threshold in your loan agreement, you're notified and given the opportunity to restore it by topping up collateral or paying down the loan. ## Get started [Speak to an expert](https://augustus.com/contact) or contact your Augustus representative to discuss terms and onboarding. # Deposits Source: https://docs.augustus.com/docs/payin/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. By default your account may not be enabled for inbound deposits and payments could be auto-returned. Turn off auto-returns under **Settings → Money**, or contact support to enable deposits on the accounts you want to receive funds on. ## Stablecoin deposits Copy your wallet address from the Dashboard under **Accounts → Details**. Senders must transfer from a **linked wallet** on a supported chain. Verify the address, chain, and amount before sending. Transfers from non-linked addresses or unsupported chains may be lost. ## Webhook events Subscribe to the following events to be notified when deposits and returns change state: | Event | Description | | ------------------ | ---------------------------------------------------------------------------------------------------- | | `deposit.received` | A new deposit arrived on one of your accounts. | | `return.initiated` | A return was initiated for a deposit. | | `return.paid` | The return was processed successfully. | | `return.failed` | The return could not be completed. | | `return.returned` | A previously paid return was reversed or returned, and the funds were credited back to your account. | ## Retrieve a deposit Get a deposit ID from the `deposit.received` webhook payload or by listing deposits. ```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) ```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) ## Returns A return sends a deposit back to the original sender. Returns reference the parent deposit and emit `return.*` webhook events as they progress. ### Create a return ```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) ```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) ### Retrieve a return ```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) ```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) ## FAQ With Deposits enabled, the payment is accepted and recorded as an unmatched deposit. Reconcile it in your own system or return the funds. Without Deposits enabled, mismatched payments may be returned automatically. Each successful deposit immediately increases the account's available balance. See [Balances](/docs/accounts/balances). No — only full returns are supported. To send back a partial amount, use a [payout](/docs/payout/payout). By default, your account is set to auto-return funds. Turn off auto-returns under **Settings → Money** to receive test deposits. # Failure reasons Source: https://docs.augustus.com/docs/payin/instant-bank-transfer/failure-reasons Understand the main failure reasons for Open Banking payments and how to handle them in your integration. When an order fails or is canceled, the `order_updated` webhook includes a `statusClassification` object with a broad `primary` category and a specific `secondary` reason. ```json theme={null} { "statusClassification": { "primary": "payment_execution_failed", "secondary": "insufficient_funds" } } ``` ## Primary classifications | Primary | Meaning | Common causes | Handling | | ------------------------------ | ------------------------------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `payment_authorization_failed` | Rejected during authorization at the bank. | Wrong credentials, canceled at bank, account restrictions. | Suggest retry, check credentials, try a different bank. | | `payment_execution_failed` | Authorized but couldn't execute. | Insufficient funds, account limits, blocked international transfer, bank rejection or outage. | Retry — if the original payment arrives late, it's auto-returned. | | `payment_abandoned` | Started but never completed. | Customer closed the browser, session timed out, canceled at the bank. | Show clear messaging, allow retry. | ## Secondary classifications | Code | Description | | --------------------------------------- | --------------------------------------------------------------------- | | `wrong_credentials` | User entered incorrect bank credentials during authentication. | | `incorrect_2fa_response` | User provided an incorrect two-factor authentication response. | | `pin_blocked` | User's PIN is blocked, e.g. after multiple failed attempts. | | `no_active_tan_methods_available` | No active TAN (Transaction Authentication Number) methods available. | | `timeout` | The payment request timed out due to slow response from bank systems. | | `connection_to_bank_failed` | The user's bank is not responding to the payment request. | | `bank_error` | The bank's system returned an error during processing. | | `bank_under_maintenance` | The user's bank is currently under maintenance. | | `insufficient_funds` | The user's account has insufficient funds for the payment. | | `account_limit_exceeded` | The payment exceeds the user's account transfer limits. | | `international_transfer_blocked` | International transfers are blocked for this account. | | `international_transfer_limit_exceeded` | The payment exceeds international transfer limits. | | `instant_transfers_not_enabled` | Instant transfers are not enabled for this account. | | `user_blocked` | The user's account is blocked or restricted. | | `unsupported_bank_account` | The bank account type is not supported for the requested transfer. | | `payment_rejected` | The payment was explicitly rejected by the bank. | | `cancelled` | The payment was canceled by the user or bank. | | `payment_not_settled` | The payment was not settled within the required timeframe. | See [Status flow](/docs/payin/instant-bank-transfer/payment-status) for the full lifecycle and [Webhooks](/webhook-getting-started/introduction) for setup. # Client integration Source: https://docs.augustus.com/docs/payin/instant-bank-transfer/iframe Optimise your client integration of Augustus Checkout for the best user experience on any platform. Recommended integration per platform: * **Desktop web** — embed via the [React SDK](https://www.npmjs.com/package/@getivy/react-sdk) or an iframe. * **Mobile web** — redirect to the Augustus-hosted checkout. * **Mobile native** — open the Augustus-hosted checkout in the user's default browser; return via deep linking. ## Backend setup Create a server-side endpoint that initiates a Checkout Session and returns the `redirectUrl` to your frontend. ```ts server/routes/checkout.ts theme={null} import express from 'express' import Ivy from '@getivy/node-sdk' const router = express.Router() const client = new Ivy() router.post('/api/checkout', async (req, res) => { const session = await client.checkoutsession.create({ referenceId: 'order_123', price: { total: req.body.amount, currency: req.body.currency || 'EUR', }, locale: req.body.locale || 'en', successCallbackUrl: 'https://example.com/success', errorCallbackUrl: 'https://example.com/error', customer: { email: 'john.doe@example.com', }, }) res.json({ url: session.redirectUrl }) }) export default router ``` ## Desktop web Use the [React SDK](https://www.npmjs.com/package/@getivy/react-sdk) to embed the checkout in your page. * Embedded iframe: append `&iframe=true` to the checkout URL. * Modal iframe: append `&popup=true` to the checkout URL. The API doesn't include these parameters — you set them at render time. The React SDK does this automatically. ### React SDK ```bash theme={null} npm install @getivy/react-sdk ``` ```tsx components/IvyCheckout.tsx theme={null} import { IvyCheckout } from '@getivy/react-sdk' export function Checkout({ amount, currency = 'EUR', locale = 'de', handleSuccess, handleCancel, }: { amount: number currency?: string locale?: string handleSuccess: (data: { redirectUrl: string; referenceId: string }) => void handleCancel: (data: { redirectUrl: string; referenceId: string }) => void }) { const response = await fetch('/api/checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ amount, currency, locale }), }) const { url } = await response.json() return ( ) } ``` The React SDK automatically appends `&iframe=true` when using embedded mode. ```css styles/ivy-checkout.css theme={null} @import "@getivy/react-sdk/dist/index.css"; .ivy-embedded-checkout-screen { width: 100%; height: 100%; border: none; } .ivy-modal-content { position: fixed; inset: 0; z-index: 999999; display: flex; align-items: center; justify-content: center; background-color: rgba(10, 10, 10, 0.25); } .ivy-modal-content .ivy-modal-iframe-container { width: 100%; height: 100%; border-radius: 16px; overflow: hidden; } @media (max-width: 450px) { .ivy-modal-content .ivy-modal-iframe-container { border-radius: 0; } } ``` ### Plain HTML (without the SDK) If you can't use React, render the iframe directly. The iframe communicates with your page via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). ```html checkout.html theme={null}
``` The iframe sends a `postMessage` with the following fields: | Field | Description | | ------------- | ----------------------------------------------------------- | | `source` | Always `"ivy"`. | | `type` | Always `"iframe"`. | | `value` | Either `"success"` or `"error"`. | | `referenceId` | Your original `referenceId` from Checkout Session creation. | The iframe `sandbox` attributes are required: * `allow-scripts` — required for the checkout to function. * `allow-same-origin` — enables secure communication. * `allow-forms` — required for payment form input. * `allow-popups`, `allow-popups-to-escape-sandbox` — required for bank redirects. * `allow-top-navigation` — required for completion redirects. * `allow="clipboard-write"` — required for copy-to-clipboard buttons. ## Mobile web On mobile, redirect to the Augustus-hosted checkout. An iframe breaks the flow when the customer moves to and from their banking app. ```javascript theme={null} function isMobile() { return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent) } async function startCheckout() { const response = await fetch('/api/checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ amount: 100, currency: 'EUR' }), }) const { url } = await response.json() if (isMobile()) { window.location.href = url } else { // Render the iframe on desktop — see above. } } ``` Make sure the `successCallbackUrl` and `errorCallbackUrl` you pass to the Checkout Session point to pages on your site where the user lands after the bank flow completes. ## Mobile native Open the checkout in the user's **default browser**. Do not use a WebView — it breaks bank authentication, deep linking, SSL, and session handling. ```javascript theme={null} // Don't do this // Do this instead Linking.openURL(checkoutUrl) ``` ### Open the checkout ```javascript React Native theme={null} import { Linking } from 'react-native' const openCheckoutInBrowser = async () => { const response = await fetch('/api/checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ amount: 100, currency: 'EUR' }), }) const { url } = await response.json() if (await Linking.canOpenURL(url)) { await Linking.openURL(url) } } ``` ```swift iOS (Swift) theme={null} import SafariServices func openCheckoutInBrowser() { guard let url = URL(string: checkoutUrl) else { return } let safariVC = SFSafariViewController(url: url) safariVC.delegate = self present(safariVC, animated: true) } ``` ```kotlin Android (Kotlin) theme={null} fun openCheckoutInBrowser() { val intent = Intent(Intent.ACTION_VIEW, Uri.parse(checkoutUrl)) intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK) startActivity(intent) } ``` ### Deep linking back to your app Configure deep linking so the user returns to your app after payment: ```javascript theme={null} import { Linking } from 'react-native' useEffect(() => { const handleDeepLink = ({ url }) => { if (url.includes('payment-success')) { navigation.navigate('PaymentSuccess') } else if (url.includes('payment-error')) { navigation.navigate('PaymentError') } } const subscription = Linking.addEventListener('url', handleDeepLink) return () => subscription.remove() }, []) ``` Configure your app's deep-linking scheme so the Augustus return URLs open your app. # Integration flow Source: https://docs.augustus.com/docs/payin/instant-bank-transfer/payment-integration Everything you need to let customers pay in money via Open Banking Create a Checkout Session for each payment attempt. It returns a `redirectUrl` where the customer authorizes the payment in their bank. Track the resulting order via webhooks. Open Banking is available only in the 2023-01-01 API ## Flow Submit payment parameters and receive a `redirectUrl`. Send the customer to `redirectUrl` for the Augustus-hosted bank selection and authorization screens. The customer lands back at your `successCallbackUrl` or `errorCallbackUrl`. Subscribe to `order_updated` webhooks for real-time status. ## Create a Checkout Session ```ts 2023-01-01 theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const session = await client.checkoutsession.create({ price: { total: 119, currency: 'EUR' }, referenceId: 'my-unique-reference-id', successCallbackUrl: 'https://my-website.com/success', errorCallbackUrl: 'https://my-website.com/try-again', paymentSchemeSelection: 'instant_preferred', market: 'DE', customer: { email: 'customer@example.com' }, }) const { redirectUrl, id } = session ``` [**POST** `/api/service/checkout/session/create` in the API Reference →](/api-reference/checkout/create-a-checkout-session) ### Configuration options | Field | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paymentSchemeSelection` | `instant_only`, `instant_preferred` (default), or `standard`. Controls whether Augustus uses instant rails (SEPA Instant, Faster Payments) or falls back to standard. Default is set per application — contact your account manager to change it. | | `market` | ISO 3166-1 alpha-2 code (e.g. `DE`, `GB`) to pre-select the country. Auto-detected from the customer's IP if omitted. Ignored if `prefill.bankId` is set. | | `customer.email` | Email of the paying customer. Enables [Remember Me](/docs/payin/instant-bank-transfer/remember-me). Must be under `customer.email`, not `prefill`. | ## Redirect the customer Redirect the customer to `session.redirectUrl`. To embed instead of redirect, see [Client integration](/docs/payin/instant-bank-transfer/iframe). ## Handle the return The customer lands at your `successCallbackUrl` or `errorCallbackUrl` with these query parameters: | Param | Type | Description | | ------------- | ------- | ------------------------------------------------------ | | `referenceId` | string | Your original reference ID. | | `order-id` | string | The Augustus order ID (success only). | | `user_closed` | boolean | `true` if the customer explicitly closed the checkout. | When `user_closed` is `true`, you can expire the Checkout Session with `client.checkoutsession.expire({ id })` to trigger webhooks and update your internal state. ## Track the order When the customer completes payment, the Checkout Session is `closed` and a new `order` is created. Subscribe to `order_updated` and handle these statuses: | Status | Action | | ---------- | -------------------------------------------------------------------- | | `paid` | Funds have settled or are guaranteed by Augustus. Fulfill the order. | | `failed` | Payment did not succeed and won't arrive. Offer a retry. | | `canceled` | Session expired or was canceled. Clean up your state. | ```ts server/routes/webhooks.ts theme={null} import express from 'express' const router = express.Router() router.post('/webhooks/augustus', express.json(), async (req, res) => { const { type, payload } = req.body if (type === 'order_updated') { switch (payload.status) { case 'paid': await fulfillOrder(payload.referenceId) break case 'failed': case 'canceled': await markOrderFailed(payload.referenceId, payload.statusClassification) break } } res.sendStatus(200) }) export default router ``` See [Status flow](/docs/payin/instant-bank-transfer/payment-status) for the full lifecycle, [Failure reasons](/docs/payin/instant-bank-transfer/failure-reasons) for `statusClassification`, and [Webhooks](/webhook-getting-started/introduction) for setup and signature verification. # Status flow Source: https://docs.augustus.com/docs/payin/instant-bank-transfer/payment-status Understand the lifecycle of an Open Banking payment and Manual Bank Transfer. Augustus tracks Open Banking and Manual Bank Transfer payments through the `order.status` field. Poll the order or subscribe to `order_updated` webhooks — status values are identical in both. ```ts 2023-01-01 theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const order = await client.orders.retrieve({ id: 'your-order-id' }) ``` ## Statuses | Status | Description | Next | Terminal | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------ | | `processing` | Order created and payment flow started. | `waiting_for_payment`, `paid`, `finalizing`, `canceled` | No | | `waiting_for_payment` | Customer authorized the payment. Settlement pending. Not guaranteed. Skipped if settlement happens first. | `paid`, `finalizing`, `failed`, `canceled` | No (yes for direct settlement) | | `finalizing` | Payment received, booking verification in progress. Usually minutes, up to 48 hours. Can still be expired via API. | `paid`, `canceled` | No | | `paid` | Funds arrived or are guaranteed by Augustus. Settlement takes anywhere from instant to 3 business days depending on scheme. Only appears when Augustus holds your collection account. | `in_refund` | Yes (unless refunded) | | `canceled` | Session expired or was canceled. Late payments are auto-returned. | — | Yes | | `failed` | Funds did not arrive in time (6 days for `instant_preferred` / `standard`, 24 hours for `instant_only`). Late payments are auto-returned. | — | Yes | | `in_refund` | Refund in flight to the customer's bank. | `refunded`, `partially_refunded` | No | | `refunded` | Fully refunded. | — | Yes | | `partially_refunded` | Part of the order was refunded. | `in_refund` | No | Payments don't always follow the common path — handle every transition in your integration. # Remember Me Source: https://docs.augustus.com/docs/payin/instant-bank-transfer/remember-me Boost conversion by simplifying your customers' checkout experience Pass a `customer.email` or a stored `customer.id` on each Checkout Session. Augustus recognizes the returning customer and skips bank selection. Pass the email under `customer.email`, not under `prefill`. Only `customer.email` is used for Remember Me recognition. ### First-time flow ### Recurring flow ## Pass a customer email ```ts 2023-01-01 theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const session = await client.checkoutsession.create({ price: { total: 119, currency: 'EUR' }, referenceId: 'my-unique-reference-id', successCallbackUrl: 'https://my-website.com/success', errorCallbackUrl: 'https://my-website.com/try-again', customer: { email: 'customer@example.com' }, }) ``` ```ts 2023-01-01 theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const customer = await client.customers.create({ email: 'customer@example.com' }) const session = await client.checkoutsession.create({ price: { total: 119, currency: 'EUR' }, referenceId: 'my-unique-reference-id', successCallbackUrl: 'https://my-website.com/success', errorCallbackUrl: 'https://my-website.com/try-again', customer: { id: customer.id }, }) ``` # Test your integration Source: https://docs.augustus.com/docs/payin/instant-bank-transfer/test-your-integration Test with sandbox banks and Sandbox Tools before going live. ## Sandbox ### Test checkout flows with sandbox banks Create a Checkout Session in sandbox and visit the `redirectUrl`. Use the credentials below to test each flow. | Bank | Country | Currency | Schemes | Credentials | Instructions | | --------------------- | ------- | -------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Test Bank market | Any | Any | SEPA Credit, SEPA Instant | Username: `random`
Password: `random`
OTP: `random` | For success, enter any OTP.
For failure, enter OTP = `666`. | | Deutsche Bank Sandbox | DE | EUR | SEPA Credit, SEPA Instant | IBAN: `DE17215730140403340300`
Account Holder Name: `random`
Branch: `615`
Account: `4033403` | €1 for success
€100 for failure | | KD Bank Sandbox | DE | EUR | SEPA Credit, SEPA Instant | IBAN: `DE39499999600000005111`
Account Holder Name: `random`
Customer ID: `VRK1234567890ALL`
Password: `password`
SCA method: `Mobile`
SCA code: `123456` | For success, select any SCA method and use SCA code `123456` if prompted. | | NatWest Sandbox | GB | GBP | Faster Payments | Username: `123456789012`
Password: displayed on screen | | | BBVA Sandbox | ES | EUR | SEPA Credit, SEPA Instant | IBAN: `ES2501822200160201933547`
Username: `user1`
Password: `1234`
SCA code: `123456` | To trigger failure, click **Cancel → Aceptar** in the bank UI. | | Alior Sandbox | PL | EUR | Elixir, SEPA Credit | Username: `60370698`
Password: `12345678` | Approve the payment in the bank interface — simulates delayed bank update. | | PKO BP Sandbox | PL | EUR | Elixir, SEPA Credit | n/a | Use buttons in the bank UI to set the desired outcome (**Sukces** → success). | ### Simulate a paid order The order starts in `processing`. Find it in the Orders table. Status updates to `paid` and a webhook fires. Sandbox tools for simulating order flows Simulation is not available with direct settlement enabled. ## Production Switch to your live API keys once sandbox testing is complete. Production uses real money. Start with small amounts. ### Recommended test cases | Test case | Expected outcome | | --------------------------------- | ------------------------------------------------------- | | Successful payments from 4+ banks | Orders reach `paid` and webhooks are received. | | Customer cancels at the bank | Order `failed` with `payment_abandoned` classification. | | Insufficient funds | Order `failed` with `insufficient_funds`. | # Manual Bank Transfer Source: https://docs.augustus.com/docs/payin/mbt/mbt Allow your customers to transfer money from their bank account manually. Manual Bank Transfer (MBT) lets a customer send funds from their bank using payment details you display. Augustus reconciles the incoming transfer against the order by reference and fires an `order_updated` webhook. Manual Bank Transfers are available only in the 2023-01-01 API ## Flow The response includes payment details to display. Show them to the customer as instructions. Order moves from `processing` to `paid` when funds arrive. See [Status flow](/docs/payin/instant-bank-transfer/payment-status). ## Create an order ```ts 2023-01-01 theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const order = await client.orders.create({ amount: 1.23, currency: 'EUR', referenceId: 'your-internal-reference', customer: { email: 'customer@example.com', }, }) ``` [**POST** `/api/service/order/create` in the API Reference →](/api-reference/order/create-an-order) ## Display the payment details The order's `destination` field contains the payment details. The shape varies by currency. ```json theme={null} { "destination": { "bankAccount": { "iban": { "iban": "DE34817329488882190", "accountHolderName": "Test Merchant", "bic": "BCIRLLLL" } }, "bankStatementReference": "ir4d23bcd816e89ef" } } ``` ```json theme={null} { "destination": { "bankAccount": { "sortCode": { "sortCode": "123456", "accountNumber": "1234567890", "accountHolderName": "John Doe" } }, "bankStatementReference": "irf1234556679" } } ``` The `bankStatementReference` is how Augustus matches the incoming transfer to your order. The customer must copy it exactly. ## Track the order Orders start in `processing`. Once funds arrive and reconcile, the order moves to `paid`. If nothing arrives or reconciliation fails, the order stays `processing` for 6 days, then moves to `failed`. Subscribe to `order_updated` or poll: ```ts 2023-01-01 theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const order = await client.orders.retrieve({ id: 'your-internal-reference' }) ``` [**POST** `/api/service/order/details` in the API Reference →](/api-reference/order/retrieve-an-order) Payments received with the wrong amount or reference are auto-returned. Instruct the customer to copy details exactly. See [Status flow](/docs/payin/instant-bank-transfer/payment-status) for the full lifecycle and [Webhooks](/webhook-getting-started/introduction) for setup. # Overview Source: https://docs.augustus.com/docs/payin/overview Introduction to payin flows and concepts. Receive funds into your Augustus accounts. Choose the flow that matches how your senders pay. Receive funds directly on an account's IBAN, sort code, ABA, or wallet address. Receive funds into accounts in your customer's name. Customer-initiated instant bank checkout. Receive funds using payment details you display. Auto-reconciled by reference. # International payouts Source: https://docs.augustus.com/docs/payout/international-payouts Send and receive USD globally over the international correspondent network, with automatic routing, payment validation, and end-to-end tracking. API resource names, fields, statuses, and webhook shapes are subject to change. Share feedback with [will@augustus.com](mailto:will@augustus.com). Send USD to beneficiaries anywhere in the world. Direct Federal Reserve clearing removes intermediary layers between your instruction and the international beneficiary for faster, more reliable international USD payments. ## Use cases * **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 1. **You instruct** — `POST /v1/payouts` with the beneficiary, amount, and rail. 2. **Augustus validates and routes** — screening, payment data validation, correspondent route resolution. 3. **Augustus sends the payment** — routed through intermediary banks to the beneficiary bank. 4. **You get real-time status** — payout status via webhooks and the API; correspondent-level hops on a separate tracking resource. 5. **Funds reach the beneficiary.** ## 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, and international USD payments can be sent and received at the virtual-account level. | ## Send USD internationally ### Create a payout ```bash theme={null} POST /v1/payouts ``` This guide focuses on international USD-specific fields. For authentication, idempotency, and error format, see [Authentication](/v1/authentication), [Idempotency](/v1/idempotency), and [Errors](/v1/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](#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](#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 flavors: IBAN-formatted accounts (mostly Europe and parts of MENA) and everything else. **IBAN beneficiary** ```json theme={null} "destination": { "name": "Acme Trading GmbH", "account_number": "DE89370400440532013000", "address": { "street": "Königsallee 1", "city": "Düsseldorf", "country": "DE", "postal_code": "40212" }, "entity_type": "business" } ``` **Non-IBAN beneficiary** ```json theme={null} "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" } } ``` **Beneficiary object** | 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). | #### 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. ### Routing You provide the beneficiary. Augustus resolves the path: 1. You provide beneficiary details including name, account number, and address. 2. Augustus uses Standard Settlement Instructions to identify the optimal route through the correspondent bank network. 3. The resolved route — including any intermediary FIs — is returned in the payout response on the `routing` field, giving you full visibility into the path your payment takes. 4. 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](#tracking). **Optional customer-provided routing.** For day one, Augustus calculates the correspondent route in all cases. Passing an `intermediary_bank` object is possible on request. ### Validation Augustus validates every payout before submission to reduce repair queues and protect 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 was canceled before submission (e.g. by manual review or your request via the Dashboard). | ```mermaid theme={null} flowchart TD pending["pending"] --> in_transit["in_transit"] in_transit --> paid["paid"] in_transit --> returns["return initiated — see Returns"] pending --> failed_canceled["failed / canceled"] ``` A webhook is fired on every status transition. See [Webhook events](#webhook-events). ### 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 reports 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 ship in the API reference when the tracking endpoints go live. ### Further information * **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 Fedwire operating hours queue and clear automatically at the next opening. For incoming bank transfers and deposit rails, see [Deposits](/docs/payin/deposits). ## Webhook events Subscribe to these events for international payouts. For payload envelope, signature verification, retry policy, and replay, see [Webhooks](/v1/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 ```json theme={null} { "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 the MVP. Augustus tracks each as a roadmap item 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 sends and receives international payments in USD only. # Overview Source: https://docs.augustus.com/docs/payout/overview Introduction to all outgoing flows Send funds from your Augustus accounts to external bank accounts and wallets. Send fiat or stablecoins to your customers and merchants. Send USD worldwide with routing, validation, and tracking. Return funds from deposits funded by Open Banking or Manual Bank Transfer. Sweep your available balance to an external destination. **Beta** Send funds in the name of your end-users from their virtual account. # Payouts Source: https://docs.augustus.com/docs/payout/payout Send money anywhere: customers, partners, suppliers, or external accounts. Send funds from an Augustus account to any external bank account or linked wallet via API or the Dashboard. ## Supported currencies * **Fiat:** EUR, GBP, USD. * **Stablecoins:** USDC (Ethereum, Solana, Polygon). ## Create a payout ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const payout = await client.payouts.create({ source_account_id: 'your-eur-account-id', amount: '100', currency: 'EUR', reference: 'Invoice 1234', destination: { type: 'iban', iban: 'DE93500105176719451585', account_holder_name: 'Chris Simon', }, }) ``` Find each Account ID in the Dashboard under **Accounts → Details**. [**POST** `/v1/payouts` in the API Reference →](/api-reference/payouts/create-payout) ```ts theme={null} 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', }, }, }, }) ``` Find each Account ID in the Dashboard under **Accounts → Details**. [**POST** `/api/service/payout` in the API Reference →](/api-reference/payout/create-a-payout) ## List payouts Fetches all payouts on your account. Filter by type and paginate as needed. ```ts theme={null} 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 →](/api-reference/payouts/list-payouts) ```ts theme={null} 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 →](/api-reference/payout/list-payouts) ## Retrieve a payout Fetches the details of a single payout by its ID. ```ts theme={null} 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 →](/api-reference/payouts/retrieve-payout) ```ts theme={null} 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 →](/api-reference/payout/retrieve-a-payout) View payouts in the [Dashboard](https://dashboard.augustus.com/dashboard/payouts). ## Statuses | Status | Description | | --------- | ------------------------------------------- | | `pending` | Request received, awaiting confirmation. | | `paid` | Initiated and funds have left your account. | | `failed` | Could not be initiated. | ## Webhooks Subscribe to payout events for real-time updates. ```ts theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const subscription = await client.webhookSubscriptions.create({ url: 'https://your-server.com/webhooks', events: ['payout.created', 'payout.initiated', 'payout.paid', 'payout.failed'], }) ``` [**POST** `/v1/webhook_subscriptions` in the API Reference →](/api-reference/webhook-subscriptions/create-webhook-subscription) ```ts theme={null} 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 →](/api-reference/webhook-subscription/create-a-webhook-subscription) | Event | Description | | ------------------ | -------------------------------------- | | `payout.created` | A payout has been created. | | `payout.initiated` | The payout is being processed. | | `payout.paid` | The payout has been successfully sent. | | `payout.failed` | The payout failed. | *** ### Closed-loop payout to a previous customer (2023-01-01 only) Reference the customer's order ID instead of bank details: ```ts 2023-01-01 theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const payout = await client.payouts.create({ amount: 100, currency: 'EUR', destination: { type: 'customer', orderId: 'order_abc123' }, }) ``` # Refunds (2023-01-01) Source: https://docs.augustus.com/docs/payout/refunds-payouts Refund all or part of an order quickly and reliably. Return part or all of a previous Open Banking or Manual Bank Transfer payment. Augustus uses instant rails (SEPA Instant, Faster Payments) where available. ## Requirements * Available balance (not pending) must cover the refund. * Multiple refunds per order are allowed, up to the original amount. * Set a reserve if you want to guarantee funds for refunds. ## Issue a refund From the Dashboard: Orders → select order → **Refund order**. Enter the amount and confirm. From the API — pass `orderId` and optionally an amount and reference: ```ts 2023-01-01 theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const refund = await client.refunds.create({ orderId: 'order_abc123', amount: 100, displayedPaymentReference: 'display this to user!', }) ``` Refunds typically arrive instantly but can take up to 2 business days depending on the customer's bank. ## Statuses | Status | Description | | -------------------- | --------------------------------------------------- | | `pending` | Initiated, processing. | | `succeeded` | Completed, funds returned. | | `partially_refunded` | Partial refund completed. | | `failed` | Failed — insufficient balance or a technical issue. | Track status in the [Dashboard](https://dashboard.augustus.com). ## Webhooks ```ts 2023-01-01 theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const subscription = await client.webhook.subscription.create({ url: 'https://your-server.com/webhooks', events: ['refund.initiated', 'refund.succeeded', 'refund.failed'], }) ``` | Event | Description | | ------------------ | ---------------------------------------------- | | `refund.initiated` | The refund has been created and is processing. | | `refund.succeeded` | The refund completed successfully. | | `refund.failed` | The refund failed. | # Settlements Source: https://docs.augustus.com/docs/payout/settlements How to settle your Operating Account balance to an external account Settlements move part or all of an **Operating Account** balance to a pre-defined external bank account or linked wallet, automatically or on demand. Use them to sweep available fiat or crypto balances for recurring treasury operations. Settle to a pre-defined bank account in EUR, GBP, or USD. Settle fiat to stablecoins in one payment flow, on demand or on a schedule. ## How it works Set your destination bank account for settlements in the [Accounts tab](https://dashboard.augustus.com/dashboard/accounts) per account under **Settlement preferences**. To enable stablecoin settlements, contact your account manager. * **Automatic:** settle daily, weekly, or monthly. * **Manual:** trigger a settlement anytime from the Dashboard or API. * **Amount:** minimum amounts apply to stablecoin settlements. Retain a buffer for refunds or payouts. Only the amount above this threshold is settled. Edit minimum balances in the [Accounts tab](https://dashboard.augustus.com/dashboard/accounts) per account under **Settlement preferences**. Settlement movements appear in your [transaction reports](/docs/accounts/reports) for reconciliation. ## Supported currencies and chains * **Fiat:** EUR, GBP, USD, and more (to local bank accounts). * **Stablecoin:** USDC (Ethereum, Solana, Polygon). Stablecoin settlement speed is limited by the blockchain and can take up to 20 minutes. To enable stablecoin settlements, contact your account manager. ## Create a settlement Trigger a manual settlement that sweeps all available balances to your preconfigured destination. ```ts 2023-01-01 theme={null} import Ivy from '@getivy/node-sdk' const client = new Ivy() const settlements = await client.beneficiaryPayouts.create() ``` You can also trigger a settlement from the Dashboard. In the **Accounts** tab, select the account to settle, enter the amount, and click **Settle funds**. ## Stablecoin settlements When the destination is a USDC wallet, the settlement automatically converts fiat to USDC at the prevailing market rate. The minimum settlement amount into USDC is 10 units of source currency (EUR, GBP, or USD). For a step-by-step API flow that retrieves an exchange rate, executes the conversion, and pays out USDC separately, see [On-ramp](/docs/On-Offramp/onramp). # Versioning Source: https://docs.augustus.com/reference/api-versions Learn how to specify which Augustus API version to use whenever you make a request to the Augustus API. ## About API Versioning The Augustus API is versioned using date. Breaking changes are released in new major versions of the date it got released(e.g., `2025-06-11`). Breaking changes are changes that can potentially break an integration. ### Breaking changes include: * Removing an entire endpoint * Removing or renaming a parameter * Removing or renaming a response field * Adding a new required parameter * Making a previously optional parameter required * Changing the type of a parameter or response field * Removing enum values * Adding a new validation rule to an existing parameter * Changing authentication or authorization requirements ### Non-breaking (additive) changes include: * Adding a new endpoint * Adding an optional parameter * Adding an optional request header * Adding a response field * Adding a response header * Adding enum values When a new Augustus API version is released, the previous API version will be supported for at least 24 months following the release of the new API version. ## Specifying API Versions We use the `X-Ivy-Version` header to specify the API Version. Your account will always have a default API Version from the date, you created your first API Key. You can overwrite this via the header for single requests. We have not had any breaking changes yet, so there is only one API Version. ## Supported API Versions
Active Released 01-01-2023
Need help with API versioning? Contact our support team. # Authentication Source: https://docs.augustus.com/reference/authentication The Augustus API uses API Keys to authenticate requests. You can view and manage your API Key in the Augustus Dashboard. ## Overview The Augustus API uses API Keys to authenticate requests. You can view and manage your API Key in the Augustus Dashboard. To request access to the Augustus Dashboard, please contact our support team. ### Your API Key carries many privileges, so be sure to keep it secure! Do not share your secret API Keys in publicly accessible areas such as GitHub, client-side code, and so forth. ## API Keys Augustus authenticates your API requests using your account's API Key. To authenticate each request to the Augustus API, set your API Key in the `X-Ivy-Api-Key` header. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. Augustus returns an authentication error `401` if the key is incorrect or outdated. You can use the Augustus Dashboard to rotate your API Key. If you're setting up Augustus through a Third-Party Platform (3PP), copy and paste your API Key in live mode to begin processing payments. ### Sandbox and Production Modes All Augustus API requests occur in either Sandbox or Production Mode. API objects in one mode aren't accessible in the other. For instance, a Sandbox User object cannot be part of a Production-Mode Checkout Session. | Type | Base URL | When to Use | How to Use | | ---------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Sandbox | `https://api.sand.getivy.de` | Use this mode as you build your app. In Sandbox Mode, payments will not be processed. | Integrate Augustus as you would in Production Mode. You will automatically be redirected to test payment flows. | | Production | `https://api.getivy.de` | Use this mode when you're ready to launch the checkout. In Production Mode, payments will be processed. | Use valid bank accounts. Use actual payment authorizations and payment flows. | ### Generate a New API Key 1. Go to your Augustus Dashboard 2. Click on the **Generate API Key** button ### By generating a new API Key, all previously generated API Keys will be revoked ### IP Allowlisting When you create an API Key in the Augustus Dashboard, you can optionally restrict it to one or more IP addresses or CIDR ranges. Once an allowlist is set, requests authenticated with that key are only accepted when they originate from an allowlisted address. Requests from any other address are rejected with a `403` response. * Both individual IP addresses and CIDR ranges are supported, for IPv4 and IPv6. * A key with no allowlist is not IP-restricted and can be used from any address. * The allowlist is fixed for the lifetime of a key. To change the allowed addresses, create a new key with the desired allowlist. Rotating a key preserves its existing allowlist. ### Code Example Here's an example of an authenticated request to the Augustus Sandbox API: ```bash cURL theme={null} curl https://api.sand.getivy.de/api/service/ping \ -H 'Content-Type: application/json' \ -H 'X-Ivy-Api-Key: ' \ -d '{}' ``` ## Webhooks Augustus may send requests to endpoints that you set up, for example, as Webhooks. ### Security & Signature All requests sent to your endpoints will include the `X-Ivy-Signature` header. Verify this value to ensure the request is coming from Augustus and not from a third party. To validate incoming requests: * Obtain the `Webhook Signing Secret` from the Augustus Dashboard * Check the `X-Ivy-Signature` Header against a newly calculated Signature for every incoming request * Calculate the signature using the request body and the `Webhook Signing Secret` with HMAC & SHA-256 Hash ### Code Examples ```javascript Node theme={null} const { createHmac } = require('crypto') const config = require('../config') /* This middleware validates the request body against the X-Ivy-Signature header. If the signature is invalid, an error is thrown. If the signature is valid, the next middleware is called. */ function validateRequest(req, res, next) { const secret = config.IVY_WEBHOOK_SIGNING_SECRET const data = req.body const expectedSignature = sign(data, secret) const signature = req.get('X-Ivy-Signature') if (signature !== expectedSignature) throw new Error('Invalid signature!') next() } /* Parameter "data" is the request/response body. The response is the X-IVY-SIGNATURE. */ function sign(data, secret) { const hmac = createHmac('sha256', secret) hmac.update(JSON.stringify(data)) return hmac.digest('hex') } ``` ```python Python theme={null} import hmac import hashlib import json import os def sign(data): return hmac.new( os.environ['IVY_WEBHOOK_SIGNING_SECRET'].encode('utf-8'), json.dumps(data).encode('utf-8'), hashlib.sha256 ).hexdigest() ``` ```php PHP theme={null} getContent(), $this->config->getWebhookSecret() ); if ($request->getHeaders('x-ivy-signature')->getFieldValue() === $hash) { return true; } return false; } ``` # Errors Source: https://docs.augustus.com/reference/errors Augustus API utilizes standard HTTP response codes to provide information about the success or failure of API requests. ## Status Codes We follow the HTTP status code conventions. See the [HTTP Status Code Summary](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status) for more details. **`2xx Range (Success):`** Codes in this range indicate a successful API request. This means the requested operation was completed as expected. **`4xx Range (Client Errors):`** Codes in this range indicate an error related to the client's request. These errors may occur due to missing required parameters, payment failures, or other client-specific issues. **`5xx Range (Server Errors):`** These codes indicate an issue with Augustus' servers. When you encounter a code in this range, it signifies an error on Augustus' side rather than an issue with the client's request. Understanding these response codes helps developers work with Augustus API effectively and handle different scenarios appropriately, ensuring smooth and reliable integration. ## Error Structure All errors return a consistent JSON structure in the response body: A human-readable message explaining what went wrong. This message is suitable for displaying to end customers or for debugging purposes. A broad category classifying the type of error. Possible values: * `api_error` - Server-side errors or unexpected issues * `invalid_request_error` - Client-side errors such as invalid parameters, authentication failures, or authorization issues * `rate_limiting` - Request was rejected due to rate limiting * `idempotency_error` - Request conflicts with a previous request using the same idempotency key A short string indicating the specific error code. You can use this to handle errors programmatically. When the error is parameter-specific, this field indicates which parameter caused the error. Useful for displaying validation errors near the appropriate form field. A URL linking to relevant documentation that provides more context about the error. DEPRECATED: A human-readable message providing additional details about the error, primarily intended for developers. DEPRECATED: The HTTP status code that corresponds to the error. DEPRECATED: Additional error context. ```json Validation Error (400) theme={null} { "message": "Amount must be greater than 0", "category": "invalid_request_error", "param": "amount", "docUrl": "https://docs.getivy.de/reference/errors" } ``` ```json Authentication Error (401) theme={null} { "message": "You are not authenticated. Please log in and try again", "category": "invalid_request_error", "docUrl": "https://docs.getivy.de/reference/authentication" } ``` ```json Server Error (500) theme={null} { "message": "An unknown error occurred. Please reach out to support. Correlation id: abc-123-def", "category": "api_error" } ``` # Idempotency Source: https://docs.augustus.com/reference/idempotency Use idempotency keys to safely retry POST requests without creating duplicate operations. ## Overview Network failures and timeouts are unavoidable. Without idempotency, retrying a failed request can create duplicate payouts, refunds, or other financial operations with real monetary consequences. Idempotency keys let you retry any POST request with the guarantee that the operation executes exactly once. ## Sending an idempotency key Use a UUID v4 as the key, or any string up to 255 characters that uniquely identifies this specific operation for your account. An internal order ID or invoice reference works well. The key is scoped to your merchant account. Include it as a header on any mutating POST request: ``` POST /api/service/checkout/session/create Idempotency-Key: 7a3b08d1-2c4e-4f5a-9b6c-1d2e3f4a5b6c Content-Type: application/json X-Ivy-Api-Key: ``` The key is optional. When omitted, the request executes normally with no idempotency guarantees. When the same key is sent again with identical parameters, the API returns the cached response without re-executing the operation. The Node SDK automatically generates a UUID v4 idempotency key for every covered POST request, so you get safe retries without any extra code. Pass your own key only when you want to control the value. ## Covered endpoints The following mutating endpoints accept the `Idempotency-Key` header: | Endpoint | Description | | ----------------------------------------------- | ----------------------------- | | `POST /api/service/beneficiary-payout/create` | Create a beneficiary payout | | `POST /api/service/checkout/session/create` | Create a checkout session | | `POST /api/service/checkout/session/expire` | Expire a checkout session | | `POST /api/service/customer/create` | Create a customer | | `POST /api/service/customer/delete` | Delete a customer | | `POST /api/service/customer/update` | Update a customer | | `POST /api/service/fx/execute` | Execute an FX conversion | | `POST /api/service/order/create` | Create an order | | `POST /api/service/order/expire` | Expire an order | | `POST /api/service/payout/create` | Create a payout | | `POST /api/service/refund/create` | Create a refund | | `POST /api/service/subaccount/create` | Create a subaccount | | `POST /api/service/webhook-subscription/create` | Create a webhook subscription | | `POST /api/service/webhook-subscription/delete` | Delete a webhook subscription | | `POST /api/service/webhook-subscription/update` | Update a webhook subscription | Read-oriented endpoints (retrieve, list, search, details) are safe to retry without an idempotency key. `POST /api/service/fx/execute` previously accepted an `idempotencyKey` field in the request body. That field still works but is deprecated. Use the `Idempotency-Key` header instead. ## Conflict behaviour Reusing the same key with different request parameters returns a `409 Conflict`: ```json 409 Conflict: mismatched parameters theme={null} { "message": "This idempotency key has already been used with different parameters.", "category": "idempotency_error", "docUrl": "https://docs.getivy.de/reference/idempotency" } ``` ```json 409 Conflict: request in progress theme={null} { "message": "A request with this idempotency key is currently being processed.", "category": "idempotency_error", "docUrl": "https://docs.getivy.de/reference/idempotency" } ``` If two requests arrive concurrently with the same key, the second returns `409 Conflict`. Retry after a short delay. Using the same key for two different operations is almost always a bug. The key is scoped globally, so the same key sent to two different routes will conflict. ## Error handling Only successful responses are cached. If the original request fails (for example, a `400` validation error), the idempotency key is released and you can retry with the same key after fixing your request. You do not need a new key to correct a mistake. ## Key retention Idempotency keys are retained for 30 days. After expiry, a previously used key is treated as new and the operation executes again. ## Code examples ```sh curl theme={null} curl --request POST \ --url https://api.getivy.de/api/service/payout/create \ --header 'X-Ivy-Api-Key: YOUR_API_KEY' \ --header 'Idempotency-Key: 7a3b08d1-2c4e-4f5a-9b6c-1d2e3f4a5b6c' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "amount": 100, "currency": "EUR", "destination": { "financialAddress": { "type": "iban", "iban": { "iban": "DE93500105176719451585", "accountHolderName": "Chris Simon" } } } }' ``` ```typescript Node SDK theme={null} import { Ivy } from "@getivy/node-sdk"; import { randomUUID } from "crypto"; const ivy = new Ivy({ apiKey: "YOUR_API_KEY" }); const payout = await ivy.payout.create( { amount: 100, currency: "EUR", destination: { financialAddress: { type: "iban", iban: { iban: "DE93500105176719451585", accountHolderName: "Chris Simon" } } } }, { idempotencyKey: randomUUID() } ); ``` # Introduction Source: https://docs.augustus.com/reference/introduction If you have any questions or feedback, please ping us an [email](mailto:help@augustus.com)! We have organized the content into the following sections: 1. **Getting Started:** Basic concepts of our API, i.e. Authentication, Versioning, Metadata, Errors 2. **REST API:** Reference of all API endpoints You can check out the Webhook Events Reference [here](/webhook-getting-started/introduction). # Metadata Source: https://docs.augustus.com/reference/metadata Most updatable Augustus objects have a Metadata parameter. You can use this parameter to attach arbitrary key-value data to these Augustus objects. ## Overview Most updatable Augustus objects have a `metadata` parameter. You can use this parameter to attach arbitrary key-value data to Augustus objects. You can specify up to 50 keys, with: * Key names up to 40 characters long * Values up to 500 characters long Metadata is useful for storing additional, structured information on an object. For example, you could store your user's corresponding unique identifier from your system on an Augustus Checkout Session object. This allows you to attach information about returning users to an Augustus Payment. When a user successfully completes the payment flow, all `metadata` parameters transfer from the Augustus Checkout Session to the Augustus Order. By default, Augustus doesn't use Metadata for any processing logic - for example, it's not used to authorize or decline payments. Your users will only see Metadata if you explicitly show it to them. Do not store sensitive information (bank account numbers, card details, etc.) in the `metadata` parameter. ## Sample Metadata Use Cases ### Link IDs Attach your system's unique IDs to an Augustus object for easy lookups: * Add your order number to a charge * Add your user ID to a customer or recipient * Add a unique receipt number to a transfer ### Refund Paper Trails Store information about: * Why a refund was created * Who created the refund * Any associated internal tracking numbers ### Recognize Returning Customers Annotate a Checkout Session object by storing an internal ID for later use. When creating a new Augustus Checkout Session for a payment flow ([See payment flow details](/docs/payin/instant-bank-transfer/payment-integration)), specify your system's internal customer ID in the `metadata` field. The example below adds an `internalCustomerId` with the value `customer_abcdefg` to the Augustus Checkout Session object: ```bash cURL theme={null} curl -X POST https://api.getivy.de/api/service/checkout/session/create \ -H 'Content-Type: application/json' \ -H 'X-Ivy-Api-Key: ' \ -d '{ "price": { "total": 100, "currency": "EUR" }, "referenceId": "my-unique-reference-id", "metadata": { "internalCustomerId": "customer_abcdefg" } }' ``` When receiving status updates ([See payment status details](/docs/payin/instant-bank-transfer/payment-status)), the `metadata` field will be included in the payload. This allows you to easily match a new Order status to an internal user - for example, to fulfill orders more quickly. # Authentication Source: https://docs.augustus.com/v1/authentication The 2026-05-01 API uses bearer tokens in the standard Authorization header to authenticate requests. ## Overview The 2026-05-01 API authenticates requests via the standard `Authorization` header with a bearer token. You can view and manage your API keys in the [Augustus Dashboard](https://dashboard.augustus.com). Your API key carries many privileges, so keep it secure. Do not share keys in publicly accessible areas such as GitHub or client-side code. ## API keys Set your API key in the `Authorization` header on every request: ```text theme={null} Authorization: Bearer {api_key} ``` All requests must be made over HTTPS. Requests over plain HTTP or without authentication will fail. ### Key format API keys are prefixed with their environment (e.g. `sandbox.`, `prod.`) so you can immediately identify which environment a key belongs to. Keys are otherwise opaque. Treat them as a single string. ### Environments | Environment | Base URL | | ----------- | ---------------------------------- | | Sandbox | `https://api.sandbox.augustus.com` | | Production | `https://api.augustus.com` | Sandbox and production are isolated. API keys and resources created in one environment are not accessible in the other. ### Key scopes Each API key carries one or more scopes that gate which resources and actions it can use. See [Scopes](/v1/scopes) for the full catalogue, alias semantics, and recommended scope sets for common integration patterns. ## Authenticated request ```bash cURL theme={null} curl https://api.augustus.com/v1/payouts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ -H "Authorization: Bearer sandbox.ak_test_eXaMpLeKeY..." ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const payout = await client.payouts.retrieve('a1b2c3d4-e5f6-7890-abcd-ef1234567890') ``` ## Errors | Status | Code | When | | ------ | ------------------------- | -------------------------------------- | | 401 | `authentication_required` | Missing or invalid API key | | 403 | `permission_denied` | Valid key but insufficient permissions | # Errors Source: https://docs.augustus.com/v1/errors The 2026-05-01 API returns consistent, structured error responses with machine-readable codes for programmatic handling. ## Error response All errors return a flat JSON object with every field always present: Broad error classification. One of: `api_error`, `authentication_error`, `idempotency_error`, `invalid_request_error`, `rate_limit_error`. Machine-readable error code for programmatic handling. Use this to branch on specific error conditions. Never parse the `message` field. Human-readable description of the error. Not a stable contract. Do not parse or branch on message content. The request parameter that caused the error, or `null` if not parameter-specific. Link to documentation explaining the error. Unique request identifier for tracing and support. Also returned as a `Correlation-Id` response header on all responses. ## Categories | Category | Meaning | | ----------------------- | --------------------------------------------------------------- | | `api_error` | Server-side failure. You did nothing wrong. Retry may help. | | `authentication_error` | Missing or invalid API key. | | `idempotency_error` | Idempotency key conflict (reuse with different params). | | `invalid_request_error` | Client-side problem: bad parameters, not found, state conflict. | | `rate_limit_error` | Too many requests. Back off and retry. | ## Error codes ### Structural codes | Code | Category | HTTP | When | | ------------------------------ | ----------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- | | `parameter_invalid` | `invalid_request_error` | 400 | Request parameter fails validation | | `parameter_missing` | `invalid_request_error` | 400 | Required parameter not provided | | `validation_error` | `invalid_request_error` | 400 | Request body fails schema validation | | `api_version_error` | `invalid_request_error` | 400 | Unknown or unsupported `api-version` header value | | `invalid_cursor` | `invalid_request_error` | 400 | Pagination cursor is malformed or could not be read | | `cursor_mismatch` | `invalid_request_error` | 400 | Pagination cursor was issued for different filters | | `idempotency_key_required` | `invalid_request_error` | 400 | POST request sent without an [`Idempotency-Key`](/v1/idempotency) header | | `authentication_required` | `authentication_error` | 401 | Missing or invalid API key | | `permission_denied` | `invalid_request_error` | 403 | Valid key, but the request is forbidden by a non-scope check (feature flag, enabled surface, beneficiary allowlist) | | `insufficient_scope` | `invalid_request_error` | 403 | Valid key, but missing one or more [scopes](/v1/scopes) the endpoint requires. Carries an additional `required_scopes` array | | `resource_not_found` | `invalid_request_error` | 404 | Resource does not exist | | `method_not_allowed` | `invalid_request_error` | 405 | HTTP method not supported on this endpoint | | `conflict` | `invalid_request_error` | 409 | Business state conflict | | `idempotency_key_already_used` | `idempotency_error` | 409 | Key reuse with different parameters | | `request_in_progress` | `idempotency_error` | 409 | Concurrent request with same key | | `payload_too_large` | `invalid_request_error` | 413 | Request body exceeds the maximum size | | `rate_limit_exceeded` | `rate_limit_error` | 429 | Too many requests | | `internal_error` | `api_error` | 500 | Unexpected server failure | | `upstream_error` | `api_error` | 500 | A required upstream service returned an error | ### Domain codes These codes refine `invalid_request_error` for specific resources. They allow finer-grained handling than the generic `parameter_invalid` or `validation_error`. | Code | HTTP | When | | --------------------------------- | ---- | --------------------------------------------------------------------------------------------------------- | | `payout_validation_failed` | 400 | Payout request fails business validation | | `conversion_validation_failed` | 400 | Conversion request fails business validation | | `quote_validation_failed` | 400 | Quote request fails business validation | | `invalid_currency` | 400 | Currency is not supported for the requested action | | `account_holder_already_existing` | 409 | An account holder with the same identity already exists. Carries an additional `existing_holder_id` field | ## Examples ```json 400 Validation theme={null} { "category": "invalid_request_error", "code": "parameter_missing", "message": "The amount parameter is required.", "param": "amount", "doc_url": "https://docs.augustus.com/v1/errors", "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` ```json 403 Insufficient scope theme={null} { "category": "invalid_request_error", "code": "insufficient_scope", "message": "Insufficient scope to perform this operation.", "param": null, "required_scopes": ["payouts:write"], "doc_url": "https://docs.augustus.com/v1/errors", "correlation_id": "e5f6a7b8-c9d0-1234-ef01-234567890123" } ``` ```json 404 Not found theme={null} { "category": "invalid_request_error", "code": "resource_not_found", "message": "No payout found with the given ID.", "param": null, "doc_url": "https://docs.augustus.com/v1/errors", "correlation_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } ``` ```json 409 Idempotency conflict theme={null} { "category": "idempotency_error", "code": "idempotency_key_already_used", "message": "This idempotency key has already been used with different parameters.", "param": null, "doc_url": "https://docs.augustus.com/v1/errors", "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } ``` ```json 429 Rate limited theme={null} { "category": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Please retry after a short delay.", "param": null, "doc_url": "https://docs.augustus.com/v1/errors", "correlation_id": "d4e5f6a7-b8c9-0123-def0-456789012345" } ``` ```json 500 Server error theme={null} { "category": "api_error", "code": "internal_error", "message": "An unexpected error occurred. Please retry or contact support.", "param": null, "doc_url": "https://docs.augustus.com/v1/errors", "correlation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ``` # Idempotency Source: https://docs.augustus.com/v1/idempotency Safely retry POST requests using the Idempotency-Key header to prevent duplicate operations. ## Overview All POST endpoints require an `Idempotency-Key` header. The API guarantees that the same operation is performed at most once, regardless of how many times the request is sent. This protects against duplicate payouts and other unintended side effects caused by network retries. Requests that omit the header, or send a blank value, are rejected with `400 idempotency_key_required`. GET requests are inherently idempotent. The header is silently ignored if sent on a GET. ## Usage Include the `Idempotency-Key` header on every POST request: ```bash cURL theme={null} curl -X POST https://api.augustus.com/v1/payouts \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" \ -H "Idempotency-Key: 7a3b08d1-2c4e-4f5a-9b6c-1d2e3f4a5b6c" \ -H "Content-Type: application/json" \ -d '{ "amount": "100.50", "currency": "EUR", ... }' ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const payout = await client.payouts.create( { source_account_id: '01234567-89ab-cdef-0123-456789abcdef', amount: '100.50', currency: 'EUR', destination: { type: 'iban', iban: 'DE89370400440532013000', account_holder_name: 'Jane Doe', }, }, { idempotencyKey: '7a3b08d1-2c4e-4f5a-9b6c-1d2e3f4a5b6c' }, ) ``` Keys can be any string up to 255 characters. V4 UUIDs work well, as do business-meaningful identifiers like an internal invoice ID. The SDK auto-generates a fresh idempotency key for every write request if you don't provide one, so you get safe retries by default. ## Replay behavior When a request with a previously used idempotency key and identical parameters is received, the API returns the cached response from the original request. The `Idempotent-Replayed: true` header distinguishes a replay from a fresh creation: ``` HTTP/1.1 200 OK Content-Type: application/json Idempotent-Replayed: true { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "payout", "status": "pending", ... } ``` ## Missing key Requests that omit the `Idempotency-Key` header or provide an empty value return `400 Bad Request`: ```json theme={null} { "category": "invalid_request_error", "code": "idempotency_key_required", "message": "The Idempotency-Key header is required for this request.", "param": "Idempotency-Key", "doc_url": "https://docs.augustus.com/v1/errors", "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } ``` ## Mismatch behavior Reusing an idempotency key with different request parameters returns `409 Conflict`: ```json theme={null} { "category": "idempotency_error", "code": "idempotency_key_already_used", "message": "This idempotency key has already been used with different parameters.", "param": null, "doc_url": "https://docs.augustus.com/v1/errors", "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } ``` ## Concurrent requests If a second request with the same key arrives while the first is still processing, the API returns `409 Conflict` with code `request_in_progress`. Retry after a short delay. Once the original completes, retries will return the cached result. ## Error handling Only successful responses are cached. If a request fails (e.g. 400 validation error), the key is released and you can retry with the same key after fixing the request. ## Key retention Idempotency keys are retained for **30 days**. After expiry, a previously used key is treated as new. ## Key scoping Keys are scoped globally across all endpoints per merchant account. Reusing the same key on a different endpoint returns the cached result from the first request or triggers a mismatch error. Different merchant accounts can use the same key independently. # Introduction Source: https://docs.augustus.com/v1/introduction Programmatic access to your Augustus account: send payouts, manage accounts, run conversions, and more. The 2026-05-01 API is a REST API for programmatic access to your Augustus account. Use it to: * Send **payouts** to bank accounts and crypto wallets * Receive **deposits** to Operating Accounts and Stablecoin Wallets, and issue **returns** * Run **conversions** between fiat and stablecoins (on- / off-ramps, FX) * Manage **accounts** and **virtual accounts**, and read **balances** and **transactions** * Subscribe to **webhooks** to react to events as they happen ## Base URLs | Environment | Base URL | | ----------- | ---------------------------------- | | Sandbox | `https://api.sandbox.augustus.com` | | Production | `https://api.augustus.com` | Use the sandbox environment for development and testing. Payments are not processed in sandbox mode. ## SDK We publish an official TypeScript SDK that wraps the API with idiomatic methods, auto-generated types for every resource, automatic retries, pagination helpers, and built-in webhook signature verification. ```bash theme={null} npm install @augustusbank/typescript-sdk ``` By default the client reads its configuration from environment variables, so you don't pass anything to the constructor: | Variable | Purpose | | ---------------------- | -------------------------------------------------------------------------------------- | | `AUGUSTUS_API_KEY` | API key used as the bearer token. See [Authentication](/v1/authentication). | | `AUGUSTUS_BASE_URL` | API base URL. Defaults to production. Set to the sandbox URL during development. | | `AUGUSTUS_WEBHOOK_KEY` | Webhook signing secret used by `client.webhooks.unwrap`. See [Webhooks](/v1/webhooks). | ```typescript theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const accounts = await client.accounts.list() ``` You can override any default by passing options to the constructor (e.g. `apiKey`, `baseURL`, `defaultHeaders`, `maxRetries`, `timeout`). See the SDK [README](https://www.npmjs.com/package/@augustusbank/typescript-sdk) for the full surface. Code samples in the rest of this section show both raw HTTP (cURL) and the SDK side by side - pick the one that fits your stack. ## Conventions The API follows consistent conventions across all resources: * **snake\_case** field names in all requests and responses * **String decimals** for amounts (e.g. `"100.50"`) to avoid floating-point precision issues * **ISO 8601 UTC** timestamps with mandatory `Z` suffix (e.g. `"2026-03-18T14:30:00Z"`) * **Explicit nulls**: every field defined in a resource schema is always present; fields with no value are `null` * **Type discriminator**: every resource includes a `type` field (e.g. `"payout"`, `"deposit"`) ## Request format Write operations use `POST` with a JSON body. Read operations use `GET` with query parameters for filtering and pagination. All requests must be made over HTTPS. All successful responses return `200 OK`. ```bash cURL theme={null} curl -X POST https://api.augustus.com/v1/payouts \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source_account_id": "01234567-89ab-cdef-0123-456789abcdef", "amount": "100.00", "currency": "EUR", "destination": { "type": "iban", "iban": "DE89370400440532013000", "account_holder_name": "Jane Doe" }, "reference": "Invoice 1234" }' ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const payout = await client.payouts.create({ source_account_id: '01234567-89ab-cdef-0123-456789abcdef', amount: '100.00', currency: 'EUR', destination: { type: 'iban', iban: 'DE89370400440532013000', account_holder_name: 'Jane Doe', }, reference: 'Invoice 1234', }) ``` ## Response format Single resources are returned as flat JSON objects without a wrapper envelope: ```json theme={null} { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "payout", "status": "pending", "amount": "100.00", "currency": "EUR", "created_at": "2026-03-18T14:30:00Z", "updated_at": "2026-03-18T14:30:00Z" } ``` List endpoints return a paginated envelope: ```json theme={null} { "data": [ ... ], "has_more": true, "next_cursor": "eyJhbGciOiJkaXIi..." } ``` ## Correlation ID Every response includes a `Correlation-Id` header with a unique request identifier. Include this value when contacting support to enable fast tracing across our systems. ## Forward compatibility The API is designed for longevity. To ensure your integration is resilient to additive changes: * **Ignore unknown fields** in response objects. New fields may be added without notice. * **Handle unknown enum values** gracefully. New values may be added to open enums (e.g. new payout statuses, new webhook event types). * **Do not depend on field ordering** in JSON responses These additive changes are not considered breaking and will not trigger a new API version. # Pagination Source: https://docs.augustus.com/v1/pagination List endpoints use cursor-based pagination with opaque cursors for efficient, consistent traversal. ## Overview All list endpoints return paginated results using cursor-based pagination. Results are ordered by `created_at` descending (newest first). ## Response envelope List endpoints return a standard envelope: ```json theme={null} { "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "payout", "status": "paid", "amount": "100.50", "currency": "EUR", "created_at": "2026-03-18T14:30:00Z", "updated_at": "2026-03-18T15:00:00Z" } ], "has_more": true, "next_cursor": "eyJhbGciOiJkaXIi..." } ``` | Field | Type | Description | | ------------- | -------------- | ----------------------------------------------------------------------------------------------------------- | | `data` | array | Array of resource objects | | `has_more` | boolean | Whether more results exist beyond this page | | `next_cursor` | string \| null | Opaque cursor to pass as the `cursor` query parameter for the next page. `null` when `has_more` is `false`. | ## Query parameters | Parameter | Type | Default | Description | | --------- | ------- | ------- | ------------------------------------------- | | `limit` | integer | 10 | Number of results per page (1-100) | | `cursor` | string | none | Opaque cursor from a previous `next_cursor` | ## Traversing pages Fetch the first page, then pass `next_cursor` to get the next: ```bash cURL theme={null} curl "https://api.augustus.com/v1/payouts?limit=25" \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" curl "https://api.augustus.com/v1/payouts?limit=25&cursor=eyJhbGciOiJkaXIi..." \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() for await (const payout of client.payouts.list({ limit: 25 })) { await processPayout(payout) } ``` The SDK's `list` method returns an async iterator that handles cursor traversal automatically - you don't need to pass `cursor` yourself. Use the iterator when you want to walk every page; pass `cursor` explicitly only if you're rendering one page at a time in your own UI. ## Important notes * Cursors are **opaque**. Do not decode, parse, or construct them. Always use the value returned by the API. * Cursors are **time-limited**. An expired cursor is rejected. Start a new list request without `cursor` if this happens. * Changing **filters** between pages invalidates the cursor. Omit `cursor` to begin pagination again when filters change. * Pagination is **forward-only**. There is no `previous_cursor`. # Scopes Source: https://docs.augustus.com/v1/scopes Each API key carries one or more scopes that gate which resources and actions it can touch. ## Overview Every API key carries one or more scopes, and the API enforces them on every request. Scopes let you: * Limit blast radius if a key leaks or is misused. * Hand a dependent (third-party integration, BI tool, automation) only the access it actually needs. Pick the narrowest scope set that covers your use case. The catalogue below describes every scope, and the [recommended scope sets](#choosing-scopes-for-a-key) section lists sensible starting points for common integration patterns. ## Scope vocabulary Scopes have the shape `resource:action`, for example `payouts:write`. Two actions are defined today: `read` and `write`. Each endpoint requires one or more scopes following its resource and HTTP verb (`GET /v1/payouts` requires `payouts:read`; `POST /v1/payouts` requires `payouts:write`). You don't have to memorise the rule. The authoritative list is `GET /v1/scopes`, and the [`required_scopes` field](#authorization-errors) on a 403 tells you exactly what an endpoint needs. ## Catalogue | Scope | Description | | ----------------------------- | ------------------------------------------------------------------ | | `account_holders:read` | View account holders and status | | `account_holders:write` | Create account holders | | `account_programs:read` | View account programs and their lifecycle status | | `accounts:read` | View accounts and holders | | `accounts:write` | Create and manage accounts | | `conversions:read` | View FX conversions | | `conversions:write` | Initiate FX conversions | | `deposits:read` | View deposits | | `events:read` | View webhook events and their payloads | | `payouts:read` | View payouts and their status | | `payouts:write` | Initiate and manage payouts | | `quotes:read` | View FX quotes (persisted and indicative) | | `returns:read` | View deposit returns | | `returns:write` | Initiate deposit returns | | `transactions:read` | View transactions | | `webhook_deliveries:read` | View webhook delivery history and outcomes | | `webhook_deliveries:write` | Redeliver webhook deliveries | | `webhook_subscriptions:read` | View webhook subscriptions | | `webhook_subscriptions:write` | Create, modify, and delete webhook subscriptions; send test events | `GET /v1/scopes` is the live source of truth (public, no authentication required). The catalogue is filtered by your request's `api-version` header, so the list reflects what's available on the version you're calling. ## Aliases Three aliases expand to a set of concrete scopes: | Alias | Expands to | | ---------------------- | ------------------------------------------------ | | `full_access` | Every scope in the catalogue | | `read_only` / `*:read` | Every `:read` scope | | `:*` | Every action for `` (e.g. `payouts:*`) | A `full_access` key automatically gains access to scopes added to the catalogue later. If you want a key whose budget is fixed at creation time, choose explicit scopes or a narrower alias. ## Choosing scopes for a key Scopes are picked at key-creation time in the [Augustus Dashboard](https://dashboard.augustus.com). Some starting points for common integration patterns: | Use case | Suggested scopes | | ------------------------------- | --------------------------------------------------------------------------- | | Server-side payouts integration | `payouts:* events:read webhook_subscriptions:write webhook_deliveries:read` | | Read-only BI / analytics | `read_only` | | Webhook receiver only | `events:read webhook_deliveries:*` | When in doubt, start narrow. If a real call returns `insufficient_scope`, the error tells you exactly what's missing, so widen and rotate the key. ## Verifying & troubleshooting ### Inspecting a key's scopes `GET /v1/api_key` returns the resolved scope set for the key authenticating the request. Useful at session start to plan within budget rather than discovering limits via 403 responses. ```bash cURL theme={null} curl https://api.augustus.com/v1/api_key \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const apiKey = await client.apiKeys.introspect() ``` ```json theme={null} { "type": "api_key", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "merchant_id": "507f1f77bcf86cd799439011", "scopes": ["payouts:read", "payouts:write", "events:read"], "api_version": "2026-05-01" } ``` ### Authorization errors A request that doesn't satisfy an endpoint's required scopes is rejected with `403 insufficient_scope`. The response carries a `required_scopes` array enumerating every scope the endpoint requires, regardless of what your key has: ```json theme={null} { "category": "invalid_request_error", "code": "insufficient_scope", "message": "Insufficient scope to perform this operation.", "param": null, "required_scopes": ["payouts:write"], "doc_url": "https://docs.augustus.com/v1/errors", "correlation_id": "e5f6a7b8-c9d0-1234-ef01-234567890123" } ``` Subtract your key's `scopes` (from `GET /v1/api_key`) from `required_scopes` to know exactly what to add when you create the next key. `insufficient_scope` is distinct from [`permission_denied`](/v1/errors), which covers non-scope authorization failures such as IP allowlist mismatches or account approval state. ## Rotating scopes The scope set on an existing key is **immutable**. To change scopes, create a new key and revoke the old one. Recommended rollout: 1. Create a new key in the [Augustus Dashboard](https://dashboard.augustus.com) with the new scope set. 2. Verify with `GET /v1/api_key` (using the new key) that `scopes` is what you expect. 3. Roll the new key out across your services (env var swap, secret rotation, etc.). 4. Revoke the old key in the dashboard once no traffic is using it. # Versioning Source: https://docs.augustus.com/v1/versioning The API uses date-based versioning via the api-version header to manage breaking changes. ## Overview The API uses date-based versioning to manage breaking changes. When a breaking change is introduced, a new version is released with a date identifier (e.g. `2026-05-01`). Your integration continues working on its current version until you explicitly upgrade. Additive changes (new fields, new enum values, new endpoints) are not versioned and are available immediately. See [Forward compatibility](/v1/introduction#forward-compatibility) for guidance on handling these. ## api-version header You can specify which API version to use on a per-request basis with the `api-version` header: ```bash cURL theme={null} curl https://api.augustus.com/v1/payouts \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" \ -H "api-version: 2026-05-01" ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus({ apiVersion: '2026-05-01' }) const payouts = await client.payouts.list() ``` If the header is omitted, the API uses the version pinned to your account. Every `/v1/*` response, including error responses, echoes the resolved version back in an `api-version` response header. Use it to confirm which version your request was actually served against. ```http theme={null} HTTP/1.1 200 OK api-version: 2026-05-01 correlation-id: 7e1d4f28-3b2a-4c5d-9e8f-1a2b3c4d5e6f ``` ## Default version Each merchant account is pinned to a default API version. New accounts are automatically pinned to the latest version at the time of creation. You can override the pinned version on any request by setting the `api-version` header. This allows you to test individual endpoints against a newer version before committing to a full upgrade. ## Pinning the SDK The SDK accepts an `apiVersion` option that is sent on every request. It can also be set via the `AUGUSTUS_API_VERSION` environment variable. When unset, the server falls back to the version pinned to your account. ```typescript theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus({ apiKey: process.env.AUGUSTUS_API_KEY, apiVersion: '2026-05-01', }) ``` ## Discovering versions `GET /v1/api_versions` returns the catalogue of publicly available versions, ordered oldest to newest. The endpoint is public and requires no authentication, so you can call it from anywhere, including from a CI job that asserts your integration is on a supported version. ```bash cURL theme={null} curl https://api.augustus.com/v1/api_versions ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const { data: versions } = await client.apiVersions.list() const latest = versions.find((v) => v.is_latest) ``` Each entry includes a `name`, a `released_at` timestamp, an `is_latest` flag, and `deprecated_at` / `sunset_at` (both `null` until the version begins its deprecation cycle). See the **API Versions** resource in the API Reference for the full response schema. ## Deprecation policy * Deprecated versions are supported for a minimum of **12 months** after deprecation notice. * Deprecated versions return a `Deprecation` response header and a `Sunset` date so you can detect usage of old versions in monitoring. * New versions are released no more than quarterly. ## Webhook versioning Each event's payload is serialised at the API version pinned to your account at the time the event is created. That version is carried on the wire in the envelope's `api_version` field and on the `Event` resource. Once an event is created its `api_version` is fixed: retries and [redeliveries](/v1/webhooks#inspecting-events-and-deliveries) always emit the same payload shape, even if you upgrade your pinned version in between. Upgrading your pinned version affects events created after the upgrade. Use the envelope's `api_version` to branch on payload shape during a version cut-over. # Webhooks Source: https://docs.augustus.com/v1/webhooks Receive real-time notifications when events occur in your account. ## Overview Webhooks deliver event notifications to your server as HTTP POST requests whenever something happens in your account, for example when a payout is created or a deposit is received. You can manage webhook subscriptions, inspect delivered events, and replay failed deliveries via the [Augustus Dashboard](https://dashboard.augustus.com), the REST API, or the SDK. See the **Webhook Subscriptions**, **Webhook Deliveries**, and **Events** resources in the API Reference for the full set of endpoints. ## Events Events follow a `resource.action` naming convention (e.g. `payout.paid`, `deposit.received`). The `payload` field in each delivery is a full snapshot of the resource at the time of the event, matching the shape returned by the corresponding API endpoint. ### Events | Event | When it fires | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `payout.created` | A payout has been created and is queued for processing. | | `payout.initiated` | The payout has been sent to the payment rail. | | `payout.paid` | The payout has settled at the destination. | | `payout.failed` | The payout could not be completed. Inspect `payload.failure` for details. | | `return.initiated` | A return of a previous deposit has been queued. | | `return.paid` | The return has settled at the destination. | | `return.failed` | The return could not be completed. | | `return.returned` | A previously paid return was reversed or returned, and the funds were credited back to your account. | | `deposit.received` | An incoming transfer has been credited to one of your accounts. | | `conversion.created` | A currency conversion has been queued. | | `conversion.succeeded` | The conversion has completed and funds are available in the target account. | | `conversion.failed` | The conversion could not be completed. | | `ping.test` | Synthetic event dispatched by the [test endpoint](#testing-a-subscription). Handlers should ignore it or use it as an integration check. | See the **Webhook Events** section in the API Reference for the full payload schema of each event. ## Managing subscriptions Webhook subscriptions are managed via the [Augustus Dashboard](https://dashboard.augustus.com) or programmatically through the API. Each subscription has an HTTPS URL and a list of event types it receives. ```bash cURL theme={null} curl -X POST https://api.augustus.com/v1/webhook_subscriptions \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/augustus", "events": ["payout.paid", "payout.failed", "deposit.received"] }' ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const subscription = await client.webhookSubscriptions.create({ url: 'https://example.com/webhooks/augustus', events: ['payout.paid', 'payout.failed', 'deposit.received'], }) ``` Subscribe to `["*"]` if you want to receive every event type, including any added in the future, without having to update your subscription. See the **Webhook Subscriptions** resource in the API Reference for the full set of endpoints. ## Payload shape All webhook deliveries use a consistent envelope. The example below shows a `payout.paid` delivery; other event types carry the same envelope but the `payload` shape matches the underlying resource. ```json theme={null} { "id": "b7c8d9e0-f1a2-3b4c-5d6e-7f8a9b0c1d2e", "type": "payout.paid", "api_version": "2026-05-01", "payload": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "payout", "status": "paid", "amount": "100.00", "currency": "EUR", "reference": "INV-2026-001", "source_account_id": "01234567-89ab-cdef-0123-456789abcdef", "destination": { "type": "iban", "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "account_holder_name": "Jane Doe" }, "failure": null, "metadata": {}, "created_at": "2026-03-18T14:30:00Z", "updated_at": "2026-03-18T15:00:00Z" }, "date": "2026-03-18T15:00:00.000Z" } ``` Unique identifier for the event. Stable across retries of the same event. Use this to deduplicate. Event type in `resource.action` format (e.g. `payout.paid`, `deposit.received`). API version the payload was serialised at. Fixed when the event is created; stable across retries and redeliveries, even if your account's pinned version changes in between. See [Webhook versioning](/v1/versioning#webhook-versioning). Full resource snapshot at the time of the event. The shape matches what the API returns for the same resource. ISO 8601 UTC timestamp when the event was created. During an API version cut-over, branch on `api_version` to handle older and newer payload shapes side-by-side until all in-flight events drain: ```typescript theme={null} switch (event.api_version) { case '2026-05-01': await handleCurrentVersion(event) break case '2026-08-01': await handleNextVersion(event) break default: await reportUnexpectedVersion(event) } ``` ## Signature verification Augustus signs webhooks using the [Standard Webhooks](https://www.standardwebhooks.com/) specification. Every delivery includes three headers for replay protection and integrity verification: | Header | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `webhook-id` | Stable delivery identifier. Same as the envelope `id`. Use this to deduplicate retries. | | `webhook-timestamp` | Unix timestamp (seconds) of the delivery attempt. | | `webhook-signature` | One or more `v1,` HMAC-SHA256 signatures, space-separated. Two signatures appear during [secret rotation](#secret-rotation). | ### Using the SDK (recommended) The Augustus SDK handles signature verification and returns a typed event object. The `unwrap` method verifies the signature, then parses and returns the event. It throws an error if verification fails. The `body` argument must be the **raw request body string**, not a parsed object. If you use a framework like Express with `express.json()`, you need to preserve the raw body for webhook routes. See the example below. ```typescript Express theme={null} import Augustus from '@augustusbank/typescript-sdk' import express from 'express' const client = new Augustus() const app = express() app.post('/webhooks', express.raw({ type: 'application/json' }), async (req, res) => { let event try { event = client.webhooks.unwrap(req.body.toString('utf-8'), { headers: req.headers }) } catch (err) { return res.sendStatus(400) } switch (event.type) { case 'payout.paid': await fulfilPayout(event.payload.id) break case 'payout.failed': await markPayoutFailed(event.payload.id, event.payload.failure) break case 'ping.test': break } res.sendStatus(200) }) ``` The SDK reads the signing secret from the `AUGUSTUS_WEBHOOK_KEY` environment variable by default. You can also pass it explicitly via the `key` option on `unwrap`: ```typescript theme={null} client.webhooks.unwrap(rawBody, { headers: req.headers, key: 'whsec_your_signing_secret', }) ``` ### Manual verification If you are not using the SDK, verify signatures manually: 1. Extract the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers 2. Construct the signed content: `{webhook-id}.{webhook-timestamp}.{raw_request_body}` 3. Compute HMAC-SHA256 using the base64-decoded key material from your signing secret (strip the `whsec_` prefix, then base64-decode) 4. Base64-encode the digest and compare with the `v1,` value(s) in the `webhook-signature` header 5. Reject deliveries where the timestamp is older than 5 minutes ```typescript theme={null} import { createHmac, timingSafeEqual } from 'crypto' function verifyWebhook( body: string, headers: Record, secret: string, toleranceSeconds = 300, ): boolean { const webhookId = headers['webhook-id'] const timestamp = headers['webhook-timestamp'] const signatures = headers['webhook-signature'] if (!webhookId || !timestamp || !signatures) return false if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false const keyMaterial = Buffer.from(secret.replace('whsec_', ''), 'base64') const toSign = `${webhookId}.${timestamp}.${body}` const expected = createHmac('sha256', keyMaterial).update(toSign, 'utf8').digest('base64') return signatures.split(' ').some((sig) => { const digest = sig.replace('v1,', '') return timingSafeEqual(Buffer.from(expected), Buffer.from(digest)) }) } ``` ## Signing secrets Your webhook signing secret is available in the [Augustus Dashboard](https://dashboard.augustus.com). Secrets follow the Standard Webhooks format with a `whsec_` prefix followed by base64-encoded key material (e.g. `whsec_dGhpcyBpcyBhbiBleGFtcGxl`). Treat the signing secret like a password. Do not expose it in client-side code or commit it to version control. ## Secret rotation You can rotate your webhook signing secret without downtime. During rotation, both the old and new secrets are active for 24 hours. The `webhook-signature` header includes signatures for both secrets during this window (space-separated), so your verification code should accept if any signature matches. At most two secrets are active at any time. If you use the SDK's `unwrap` method, rotation is handled automatically. ## Testing a subscription To verify that your receiver is reachable and signature verification is correctly wired up, trigger a synthetic delivery to any subscription. Augustus dispatches a signed `ping.test` event through the real pipeline, using the same signing, headers, and retry schedule as a production event. ```bash cURL theme={null} curl -X POST https://api.augustus.com/v1/webhook_subscriptions/b7c8d9e0-f1a2-3b4c-5d6e-7f8a9b0c1d2e/send_test_event \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const event = await client.webhookSubscriptions.sendTestEvent( 'b7c8d9e0-f1a2-3b4c-5d6e-7f8a9b0c1d2e', ) ``` Test deliveries behave like any other event with one exception: failures do **not** increment the subscription's health counters or trigger failure-notification emails, so you can safely test against intentionally broken endpoints. The endpoint is rate-limited per merchant. ## Inspecting events and deliveries Every event Augustus sends you is recorded and queryable for **30 days** via the API. * **Events** (`GET /v1/events`, `GET /v1/events/:id`) represent the facts that happened on your account. Each event has a stable `id` (the same `id` you receive in the webhook envelope) and the full payload snapshot. ```bash cURL theme={null} curl "https://api.augustus.com/v1/events?event_type=payout.failed&created_at.gte=2026-03-01T00:00:00Z" \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const events = await client.events.list({ event_type: 'payout.failed', created_at: { gte: '2026-03-01T00:00:00Z' }, }) ``` * **Webhook Deliveries** (`GET /v1/webhook_deliveries`, `GET /v1/webhook_deliveries/:id`) represent the individual delivery attempts against your subscriptions. One event can fan out to multiple deliveries if you have multiple matching subscriptions. Each delivery carries an `attempts[]` log with per-attempt status and HTTP status code returned by your receiver. ```bash cURL theme={null} curl "https://api.augustus.com/v1/webhook_deliveries?status=failed&created_at.gte=2026-03-01T00:00:00Z" \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() const failedDeliveries = await client.webhookDeliveries.list({ status: 'failed', created_at: { gte: '2026-03-01T00:00:00Z' }, }) ``` If a delivery failed or you want to replay it, trigger a fresh attempt with: ```bash cURL theme={null} curl -X POST https://api.augustus.com/v1/webhook_deliveries/7e1d4f28-3b2a-4c5d-9e8f-1a2b3c4d5e6f/redeliver \ -H "Authorization: Bearer $AUGUSTUS_API_KEY" ``` ```typescript SDK theme={null} import Augustus from '@augustusbank/typescript-sdk' const client = new Augustus() await client.webhookDeliveries.redeliver('7e1d4f28-3b2a-4c5d-9e8f-1a2b3c4d5e6f') ``` Redelivery creates a new delivery attempt against the same subscription using the same event payload and signing headers, so your receiver can treat it exactly like any other delivery and deduplicate via `webhook-id`. ## Retry policy Failed deliveries are retried with exponential backoff for up to 15 attempts total, spanning approximately 54 hours. Deliveries that fail all attempts are marked as permanently failed and can be inspected and replayed via the [Webhook Deliveries API](#inspecting-events-and-deliveries). Your endpoint should return a `2xx` status code within 25 seconds to acknowledge receipt. ## Event ordering Event delivery order is not guaranteed. Your endpoint should handle out-of-order delivery gracefully and use the `webhook-id` header (or the envelope `id` field) to deduplicate retries. # Authentication Source: https://docs.augustus.com/webhook-getting-started/authentication When sending webhooks to your endpoints, Augustus will sign the request with a secret key. You can view and manage your secret key in the Augustus Dashboard. ## Overview All requests sent to your endpoints will include the `X-Ivy-Signature` header. Verify this value to ensure the request is coming from Augustus and not from a third party. To validate incoming requests: * Obtain the `Webhook Signing Secret` from the Augustus Dashboard * Check the `X-Ivy-Signature` Header against a newly calculated Signature for every incoming request * Calculate the signature using the request body and the `Webhook Signing Secret` with HMAC & SHA-256 Hash Only if the signature is valid, continue processing the request! If the signature is invalid, return a 4xx status code and do not process the request. ### Code Examples ```typescript TypeScript theme={null} const { createHmac } = require('crypto') const config = require('../config') // This middleware validates the request body against the X-Ivy-Signature header. // If the signature is invalid, an error is thrown. // If the signature is valid, the next middleware is called. function validateRequest(req, res, next) { const secret = config.IVY_WEBHOOK_SIGNING_SECRET const data = req.body const expectedSignature = sign(data, secret) const signature = req.get('X-Ivy-Signature') if (signature !== expectedSignature) throw new Error('Invalid signature!') next() } // Parameter "data" is the request/response body. // The response is the X-Ivy-Signature. function sign(data, secret) { const hmac = createHmac('sha256', secret) hmac.update(JSON.stringify(data)) return hmac.digest('hex') } ``` ```python Python theme={null} import hmac import hashlib import json import os def sign(data): return hmac.new( os.environ['IVY_WEBHOOK_SIGNING_SECRET'].encode('utf-8'), json.dumps(data).encode('utf-8'), hashlib.sha256 ).hexdigest() ``` ```php PHP theme={null} getContent(), $this->config->getWebhookSecret() ); if ($request->getHeaders('x-ivy-signature')->getFieldValue() === $hash) { return true; } return false; } ``` # Introduction Source: https://docs.augustus.com/webhook-getting-started/introduction Receive event notifications from Augustus through POST requests to your webhook endpoint. ## Overview Augustus Webhook system allows you to receive event notifications whenever specific actions occur in your integration. These notifications are sent as `POST` requests to your designated webhook endpoint. ### Key Uses * Update your internal system state * Trigger follow-up actions * Track status changes in real-time You can create new *Webhook Subscriptions* through either the Augustus API or Dashboard to: * Receive specific events for your integration * Configure new webhook endpoints All Webhooks must be validated. Augustus signs them with your *Webhook Signing Secret*. Please review the implementation details in our [Authentication documentation](/reference/authentication#webhooks). ## Events Events follow a `resource.action` naming convention (e.g. `order.updated`, `payout.paid`). The `payload` field in each delivery is a full snapshot of the resource at the time of the event. Click any event to see its full payload schema. ### Available events | Event | When it fires | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | [`order.created`](/webhook-event/order-created) | A new order has been created. | | [`order.updated`](/webhook-event/order-updated) | An order's status has changed (e.g. `processing` → `paid`, `failed`, `canceled`). | | [`checkout_session.created`](/webhook-event/checkout-session-created) | A Checkout Session has been created. | | [`checkout_session.updated`](/webhook-event/checkout-session-updated) | A Checkout Session's state has changed. | | [`checkout_session.completed`](/webhook-event/checkout-session-completed) | The customer completed the Checkout Session. | | [`checkout_session.expired`](/webhook-event/checkout-session-expired) | The Checkout Session expired or was explicitly cancelled. | | [`refund.initiated`](/webhook-event/refund-initiated) | A refund has been queued. | | [`refund.succeeded`](/webhook-event/refund-succeeded) | The refund has settled to the customer. | | [`refund.failed`](/webhook-event/refund-failed) | The refund could not be completed. | | [`payout.created`](/webhook-event/payout-created) | A payout has been created. | | [`payout.initiated`](/webhook-event/payout-initiated) | The payout has been sent to the payment rail. | | [`payout.updated`](/webhook-event/payout-updated) | A payout's state has changed. | | [`payout.paid`](/webhook-event/payout-paid) | The payout has settled at the destination. | | [`payout.failed`](/webhook-event/payout-failed) | The payout could not be completed. | | [`user_payout.initiated`](/webhook-event/user-payout-initiated) | An end-user payout has been sent to the payment rail. | | [`user_payout.paid`](/webhook-event/user-payout-paid) | The end-user payout has settled at the destination. | | [`user_payout.failed`](/webhook-event/user-payout-failed) | The end-user payout could not be completed. | | [`payout_report.requested`](/webhook-event/payout-report-requested) | A payout report has been requested and is ready or being generated. | | [`fx.initiated`](/webhook-event/fx-initiated) | An FX conversion has been queued. | | [`fx.succeeded`](/webhook-event/fx-succeeded) | The FX conversion has completed and funds are available in the target account. | | [`fx.failed`](/webhook-event/fx-failed) | The FX conversion could not be completed. | | [`mandate.setup_started`](/webhook-event/mandate-setup-started) | A mandate setup flow has started. | | [`mandate.setup_succeeded`](/webhook-event/mandate-setup-succeeded) | The mandate has been successfully set up. | | [`mandate.setup_failed`](/webhook-event/mandate-setup-failed) | The mandate setup failed. | | [`mandate.revoked`](/webhook-event/mandate-revoked) | The mandate has been revoked. | | [`data_session.completed`](/webhook-event/data-session-completed) | An Open Banking data session has completed. | | [`merchant.updated`](/webhook-event/merchant-updated) | Your merchant account settings have changed. | | [`merchant_app.updated`](/webhook-event/merchant-app-updated) | An application (API key configuration) has been updated. | ## Managing Webhook Subscriptions The Augustus API provides several endpoints to manage your webhook subscriptions. Here are the key operations: ### Create a New Subscription To create a new subscription, use the [Create a Webhook Subscription](/webhook-subscription/create-a-webhook-subscription) endpoint: Your webhook endpoint URL where notifications will be sent Array of event names you want to subscribe to ### Update an Existing Subscription To modify an existing subscription, use the [Update a WebhookSubscription](/webhook-subscription/update-a-webhook-subscription) endpoint: The Webhook Subscription ID to update New webhook endpoint URL Updated array of events to subscribe to ### Delete a Subscription To remove a subscription, use the [Delete a WebhookSubscription](/webhook-subscription/delete-a-webhook-subscription) endpoint: The Webhook Subscription ID to delete ## Handling Webhooks ### Webhook Data Structure Each webhook notification contains the following data: ```json Webhook Payload Structure theme={null} { "id": "string", // Unique webhook ID for resending via /api/service/webhook/trigger "type": "string", // Event type identifier "payload": {}, // Event-specific data object "date": "date" // Webhook timestamp } ``` For detailed information about event-specific payloads, see the [Webhook Events documentation](/webhook-event/order-updated). ### Retry Mechanism A webhook delivery is only considered successful when your endpoint responds with `HTTP Status 200`. For failed deliveries, Augustus implements an exponential backoff retry schedule: * 30 seconds after initial failure * 22 seconds after 1st retry * 140 seconds after 2nd retry * 541 seconds after 3rd retry * 1,426 seconds after 4th retry * 3,200 seconds after 5th retry * Continues up to the 15th retry (\~54 hours after 14th) After 15 unsuccessful retries, Augustus stops delivery attempts and sends you an email notification. ### Allow List IP Addresses If your server implements IP filtering, add these Augustus webhook IPs to your allowlist: ```text theme={null} 18.159.27.193 3.120.50.145 18.158.26.25 18.158.95.0 3.122.16.89 ``` ```text theme={null} 3.66.64.118 18.158.26.25 18.158.95.0 3.122.16.89 ``` ### Local Development Testing Since localhost isn't accessible from the internet, we recommend using [ngrok](https://ngrok.com) for local webhook testing. For detailed guidance on setting up ngrok for webhook development, see [this guide](https://dev.to/mmascioni/testing-and-debugging-webhooks-with-ngrok-4alp). ## Webhook Logs in the Dashboard The Augustus Dashboard provides a comprehensive Webhook Logs view to help you monitor, debug, and manage webhook deliveries in real time. Augustus Dashboard Webhook Logs overview **Key features:** * See a paginated history of all webhook deliveries for each subscription * View delivery status (Delivered, Failed, etc.) at a glance * Inspect event type and timestamp for each webhook * Click any log entry to see full request and response payloads * Manually resend individual webhook events for troubleshooting * Filter or search by event type, status, or date * Bulk history navigation for large volumes of events Use the Dashboard's Webhook Logs to quickly identify delivery issues, verify event payloads, and ensure your integration is working as expected.