Bank Account

15 min

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.