> ## 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.
# Add a bank account
> Save a bank account for the business. Where the bank offers a name check, it runs at once: a clear mismatch is saved but never paid, and `payableReason` says so. Needs a live key. For a platform acting on a business it manages, bank accounts by API must have been opened for your platform; ask us. Every account added through a platform's key is emailed to the platform's owner and to the business's owner. The account number is never stored: we keep the last four characters and a hash.
Needs a live key. For a platform acting on a business it manages, ask us to open bank accounts by API for your platform first; until then the call gets `403 bank_accounts_by_api_closed`. Where the bank offers a name check, it runs at once: a clear mismatch is saved but never paid, and `payableReason` says so; `partial` and `unknown` are paid. Every account added through a platform's key is emailed to the platform's owner and to the business's owner. We keep the last four digits and a hash, never the number.
The flow end to end, with the SDK.
Managing businesses, start to finish.
## OpenAPI
````yaml POST /gateway/bank-accounts
openapi: 3.1.0
info:
title: AgentaOS Gateway API
version: 1.0.0
description: >-
The AgentaOS REST API: payment links, checkouts, subscriptions, customers,
invoices, and the unified transactions feed. This is the same API the
TypeScript SDK (`@agentaos/pay`) and the `agenta` CLI call underneath.
## Money model
- **Decimal currency units (`number`)**: a plain `amount` field (on a create
body, a Payment Link, a Checkout's `amount_override`, or an Invoice's
`amount`/`fiat_amount`/`tax_amount`) is in currency units. `49.99` means EUR
49.99, never cents.
- **Integer minor units (`number`)**: exactly one field breaks that rule:
`unitAmountMinor` on a Subscription. It is an integer count of the smallest
currency unit (`1999` means EUR 19.99), named with a `Minor` suffix
specifically so it is never confused with a plain `amount`. The `money`
object on Transactions and the `earnings` object on a retrieved Invoice are
also integer minor units, computed server-side.
- **String, on webhooks**: the `amount` inside a webhook payload's `data`
object is a string (e.g. `"49.99"`), since JSON numbers silently drop
trailing zeros and this value must round-trip exactly for accounting.
## Naming convention
Most response fields mirror the underlying database column and are
`snake_case` (`created_at`, `seller_mode`, `buyer_email`, ...). A small
number of computed convenience fields are camelCase with no snake_case
equivalent: `checkoutUrl` on Checkouts and Payment Links, `sellerMode` on
Payment Links specifically, `money` on Transactions, and `earnings` on a
single retrieved Invoice. Two resources (Subscriptions and Customers) are
fully camelCase end to end.
## Pagination
Every list endpoint takes `limit` and `offset` and returns `{ items, total,
hasMore }`. `hasMore` is computed server-side (`offset + items.length <
total`); never derive it client-side.
contact:
name: AgentaOS
url: https://agentaos.ai
license:
name: Proprietary
url: https://agentaos.ai
servers:
- url: https://api.agentaos.ai/api/v1
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Payment Links
description: >-
Reusable, shareable payment products: a fixed amount and description
behind one URL.
- name: Checkouts
description: >-
One attempt to collect one payment, standalone or built from a payment
link. Wire path is `/gateway/sessions`; the SDK and CLI call this resource
"checkout".
- name: Subscriptions
description: >-
Merchant-side read and management surface for recurring plans. Created
automatically when a buyer pays a `type: subscription` payment link.
- name: Customers
description: 'Read-only surface: everyone who has paid you or been sent an invoice.'
- name: Invoices
description: >-
Every checkout issues an invoice. List, retrieve, void, export, and
download PDFs/receipts.
- name: Transactions
description: >-
The unified activity feed: every inbound payment and outbound send, across
every rail, in one list.
- name: Businesses
description: >-
For platforms: the businesses you manage, a client's business or another
app of your own company. To act as one of them on any other endpoint, send
its id in the `AgentaOS-Account` header. Every field on this resource is
camelCase on the wire.
- name: Bank Accounts
description: >-
Where payouts go: the bank accounts of a business, as thin references
(holder, last four digits, the name-check result), never the account
number. For a platform: with the `AgentaOS-Account` header these act on a
business you manage, once we have opened bank accounts by API for your
platform. Adding an account needs a live key.
paths:
/gateway/bank-accounts:
post:
tags:
- Bank Accounts
summary: Add a bank account
description: >-
Save a bank account for the business. Where the bank offers a name
check, it runs at once: a clear mismatch is saved but never paid, and
`payableReason` says so. Needs a live key. For a platform acting on a
business it manages, bank accounts by API must have been opened for your
platform; ask us. Every account added through a platform's key is
emailed to the platform's owner and to the business's owner. The account
number is never stored: we keep the last four characters and a hash.
operationId: createBankAccount
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBankAccountParams'
example:
currency: EUR
type: iban
accountHolderName: Seller GmbH
legalType: BUSINESS
details:
IBAN: DE89370400440532013000
responses:
'201':
description: The saved account, as a thin reference.
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccount'
'400':
description: 'The form was refused: `RECIPIENT_INVALID`, with one entry per field.'
content:
application/json:
schema:
type: object
properties:
statusCode:
type: integer
example: 400
code:
type: string
example: RECIPIENT_INVALID
message:
type: string
fieldErrors:
type: array
items:
type: object
properties:
path:
type: string
example: details.IBAN
message:
type: string
example: Not a valid IBAN.
required:
- path
- message
required:
- statusCode
- code
- fieldErrors
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/BankAccountsForbidden'
components:
schemas:
CreateBankAccountParams:
type: object
properties:
currency:
type: string
description: The payout currency. EUR and USD are supported.
type:
type: string
description: 'The account type from the requirements: `iban`, `sort_code`, `aba`.'
accountHolderName:
type: string
description: >-
The name on the bank account, as the bank holds it. A clear mismatch
is saved but not paid.
legalType:
type: string
enum:
- PRIVATE
- BUSINESS
details:
type: object
additionalProperties: true
description: >-
The fields the requirements asked for, for example `{ "IBAN":
"DE89…" }`. Never stored: we keep the last four characters and a
hash.
required:
- currency
- type
- accountHolderName
- legalType
- details
BankAccount:
type: object
description: >-
A bank account as we keep it: a thin reference. The account number
itself stays with our bank partner.
properties:
id:
type: string
format: uuid
currency:
type: string
description: Upper-case, `EUR` or `USD`.
account_type:
type: string
description: 'The corridor: `iban`, `sort_code`, `aba`.'
account_identifier_last4:
type: string
description: The last four characters of the account number.
account_holder_name:
type: string
legal_type:
type: string
enum:
- PRIVATE
- BUSINESS
name_match_status:
type: string
enum:
- success
- partial
- failed
- unknown
description: >-
How the holder name compared with the name the bank holds, where the
bank offers that check (not for every currency). `failed` is never
paid; `partial` and `unknown` are paid.
active:
type: boolean
payable:
type: boolean
description: >-
Can the next payout go to this account right now: active, and the
name check did not fail.
payableReason:
type:
- string
- 'null'
description: 'When `payable` is false: why, in a sentence for the merchant.'
required:
- id
- currency
- account_type
- account_identifier_last4
- account_holder_name
- legal_type
- name_match_status
- active
- payable
- payableReason
Error:
type: object
description: >-
Every non-2xx response is JSON in this shape. Every response (success or
error) also carries an `x-request-id` response header; send that header
on your request to have your own id echoed back, otherwise the server
mints one. On errors the same id is repeated in the `requestId` body
field.
properties:
statusCode:
type: integer
description: Same as the HTTP status code.
code:
type: string
description: >-
Present on some refusals: a stable machine-readable reason, e.g.
`live_key_required`.
message:
description: >-
Human-readable. A validation failure (400) returns an array of
per-field messages instead of one string.
anyOf:
- type: string
- type: array
items:
type: string
errors:
type: array
description: >-
Present on 400 validation failures: one entry per invalid field. The
flat human-readable strings stay in `message` for back-compat; this
is the machine-readable, per-field view.
items:
type: object
properties:
field:
type: string
description: >-
Name of the invalid field, dot-notated for nested properties
(e.g. `checkoutFields.0.type`).
message:
type: string
description: Validation messages for that field, joined with `, `.
required:
- field
- message
requestId:
type: string
description: >-
Correlation id, identical to the `x-request-id` response header.
Include it when contacting support. On success it is available on
the header only, not the body.
timestamp:
type: string
format: date-time
required:
- statusCode
- message
- timestamp
responses:
Unauthorized:
description: Missing or invalid `x-api-key`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
statusCode: 401
message: Invalid API key
timestamp: '2026-08-06T12:00:00.000Z'
BankAccountsForbidden:
description: >-
A test key (`live_key_required`); a business you do not manage (`You
cannot act as this business.`); or, for a platform key, bank accounts by
API not opened for your platform (`bank_accounts_by_api_closed`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
statusCode: 403
message: >-
Bank accounts by API are not enabled for your platform. Ask us to
open it, or add the account from the dashboard.
code: bank_accounts_by_api_closed
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Your secret key, from app.agentaos.ai -> Settings -> Developers -> API
Keys. The key's prefix is both its identity and its environment:
`sk_test_...` (sandbox, free, no verification) or `sk_live_...` (real
money, requires business verification). A missing or invalid key returns
401.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.