Bank Account
Bank-account endpoints manage organization-scoped fiat settlement accounts. Bank-account data is sensitive: avoid logging full account and routing numbers, and preserve the organization/sub-organization scope returned by the API.
List bank accounts
GET /api/external/bank_accounts/?limit={limit}&cursor={cursor}&{filters}
Query parameters
Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Requested page size. SDK default: 20. |
cursor | string | null | No | Cursor for the next page. |
Filters | Record<string, string> | No | Bank-account filters accepted by the endpoint. |
Request example
{
"query": {
"limit": 20,
"cursor": null
}
}Response
interface BankAccountListResponse {
results: BankAccount[];
nextCursor?: string | null;
hasNext?: boolean;
}JSON example
{
"results": [
{
"id": "bank_account_123",
"orgId": "org_456",
"subOrgId": "sub_org_123",
"orgEntityId": "org_entity_123",
"createdById": "api_user_123",
"createdAt": "2026-08-04T10:30:00Z",
"updatedAt": "2026-08-04T10:30:00Z",
"isDeleted": false,
"status": "PENDING",
"accountNumber": "111222333",
"accountName": "Acme Corp",
"routingNumber": "021000021",
"clientBankAccountId": "erp-bank-001",
"paymentMethod": "US_ACH",
"bankName": "Chase",
"streetLine": "270 Park Avenue",
"city": "New York",
"state": "NY",
"postalCode": "10017",
"country": "US"
}
],
"nextCursor": "eyJpZCI6ImJhbmtfYWNjb3VudF8xMjMifQ==",
"hasNext": true
}JavaScript SDK
getBankAccounts(
params?: Record<string, string>,
limit?: number,
cursor?: string | null,
): Promise<BankAccountListResponse>Retrieve a bank account
GET /api/external/bank_accounts/{bankAccountId}/
Request example
{
"path": {
"bankAccountId": "bank_account_123"
}
}Response
{
"id": "bank_account_123",
"orgId": "org_456",
"subOrgId": "sub_org_123",
"orgEntityId": "org_entity_123",
"createdById": "api_user_123",
"createdAt": "2026-08-04T10:30:00Z",
"updatedAt": "2026-08-04T10:30:00Z",
"isDeleted": false,
"status": "PENDING",
"accountNumber": "111222333",
"accountName": "Acme Corp",
"routingNumber": "021000021",
"clientBankAccountId": "erp-bank-001",
"paymentMethod": "US_ACH",
"bankName": "Chase",
"streetLine": "270 Park Avenue",
"city": "New York",
"state": "NY",
"postalCode": "10017",
"country": "US"
}JavaScript SDK
getBankAccountById(bankAccountId: string): Promise<BankAccount>Create a bank account
POST /api/external/bank_accounts/
The fields required in practice depend on the country, payment method, and provider. The SDK marks every property optional; send the complete set required for the selected rail.
Request body
{
"subOrgId": "sub_org_123",
"accountNumber": "111222333",
"accountName": "Acme Corp",
"routingNumber": "021000021",
"clientBankAccountId": "erp-bank-001",
"paymentMethod": "US_ACH",
"bankName": "Chase",
"streetLine": "270 Park Avenue",
"city": "New York",
"state": "NY",
"postalCode": "10017",
"country": "US"
}Field | Type | Required in SDK | Description |
|---|---|---|---|
subOrgId | string | No | Sub-organization that owns the account. Set only at creation. |
accountNumber | string | No | Bank account number. |
accountName | string | No | Account-holder name. |
routingNumber | string | No | Domestic routing identifier where applicable. |
clientBankAccountId | string | No | Client-controlled bank-account reference. |
paymentMethod | string | No | Payment rail, for example US_ACH, US_WIRE, SEPA, SWIFT, or BANK_TRANSFER. |
bankName | string | No | Bank name. |
streetLine, city, state, postalCode, country | string | No | Bank or beneficiary address fields required by the selected rail. |
Response
{
"id": "bank_account_123",
"orgId": "org_456",
"subOrgId": "sub_org_123",
"orgEntityId": "org_entity_123",
"createdById": "api_user_123",
"createdAt": "2026-08-04T10:30:00Z",
"updatedAt": "2026-08-04T10:30:00Z",
"isDeleted": false,
"status": "PENDING",
"accountNumber": "111222333",
"accountName": "Acme Corp",
"routingNumber": "021000021",
"clientBankAccountId": "erp-bank-001",
"paymentMethod": "US_ACH",
"bankName": "Chase",
"streetLine": "270 Park Avenue",
"city": "New York",
"state": "NY",
"postalCode": "10017",
"country": "US"
}JavaScript SDK
interface CreateBankAccountRequest {
subOrgId?: string;
accountNumber?: string;
accountName?: string;
routingNumber?: string;
clientBankAccountId?: string;
paymentMethod?: string;
bankName?: string;
streetLine?: string;
city?: string;
state?: string;
postalCode?: string;
country?: string;
}
createBankAccount(request: CreateBankAccountRequest): Promise<BankAccount>Approval flow
const bankAccount = await apiClient.createBankAccount(request);
const approved = await apiClient.createBankAccountApproval(bankAccount);
// Convenience helper: create, then approve.
const approvedBankAccount =
await apiClient.createBankAccountWithApproval(request);Creation can return a PENDING account while its change request is awaiting approval. Use the returned id to retrieve the current status.