> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentaos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bank accounts by API

> Save a bank account for a business you manage from your own app. The bank confirms the holder name; we keep only the last four digits.

<Info>
  <span className="preview-pill">Private preview</span> Working end to end for the accounts that use it; details can still change. Tell us at [contact@agentaos.ai](mailto:contact@agentaos.ai) before you rely on it, and we support you directly. See [Product release phases](/getting-started/release-phases).
</Info>

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](/guides/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

<Steps>
  <Step title="Ask for the fields">
    The fields depend on the currency: an IBAN for EUR, a routing and an account number for USD.

    ```typescript theme={"system"}
    const forSeller = new AgentaOS(process.env.AGENTAOS_API_KEY!, { business: seller.id });
    const { quoteId, requirements } = await forSeller.bankAccounts.requirements('EUR');
    ```

    `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.
  </Step>

  <Step title="Send the answers">
    ```typescript theme={"system"}
    const account = await forSeller.bankAccounts.create({
      currency: 'EUR',
      type: 'iban',
      accountHolderName: 'Seller GmbH',
      legalType: 'BUSINESS',
      details: { IBAN: 'DE89370400440532013000' },
    });
    ```

    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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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

| Call | What it does |
| - | - |
| `bankAccounts.requirements(currency)` | The fields this currency needs |
| `bankAccounts.refreshRequirements({ quoteId, details })` | The fields again after an answer that changes them |
| `bankAccounts.create(params)` | Save an account, needs a live key |
| `bankAccounts.list()` | The active accounts, thin references |
| `bankAccounts.deactivate(id)` | Retire one, needs a live key |

The same calls are in the [API reference](/api-reference/bank-accounts/create) as `/gateway/bank-accounts`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.