Skip to main content
Private preview Working end to end for the accounts that use it; details can still change. Tell us at contact@agentaos.ai before you rely on it, and we support you directly. See Product release phases.
A marketplace or a platform whose sellers never log in here can save each seller’s bank account from its own app. The account is the seller’s: payouts for that business go to it, and where the bank offers a name check, a clear mismatch is saved but never paid.

​
Before you start

  • Ask us to open bank accounts by API for your platform. It is off until we switch it on, because a key that can add a payout account can move money. We open it for one platform at a time, after a conversation.
  • Use a live key. A test key gets 403 live_key_required.
  • Act as the business: pass { business: id } on the call or create the client with it. See Build a platform.
Without the switch, adding and retiring an account get 403 bank_accounts_by_api_closed; asking for the requirements and listing still work. The business’s bank account can still be added from the dashboard: open the business and go to Balances, Payout accounts.

​
Add an account

1

Ask for the fields

The fields depend on the currency: an IBAN for EUR, a routing and an account number for USD.
requirements is a form schema, one entry per account type, each with its fields and validation. When a field is marked refreshRequirementsOnChange, such as the legal type, send the answers so far to refreshRequirements({ quoteId, details }) and render the fields again.
2

Send the answers

You get the account back as a thin reference: accountIdentifierLast4, accountHolderName, nameMatchStatus and payable. We keep the last four digits and a hash. The account number stays with our bank partner.
3

Read the name check

Where the bank offers a name check, it runs at once; not every currency has one. payable: true means the next payout can go there. nameMatchStatus: "failed" means the account is saved but never paid: the name on the account is not the business’s. partial and unknown are paid. payableReason says why in a sentence you can show.

​
What happens next

  • We email the owners. Every account added through your key is emailed to your owners and, when the business has any, to the business’s owners, one email each: the business, the currency, the last four digits, the holder name, that it came through your API key, whether the next payout goes there, and to reply at once if nobody at the platform did this.
  • Payouts use the newest usable account per currency, unless the business chose one. A seller who logs in sees the account on their Payout accounts page like any other.
  • Retire an account with deactivate(id). A currency that pointed at it falls back to the newest usable account.

​
The calls

The same calls are in the API reference as /gateway/bank-accounts.