Accounts

An account is the main container for identity, permissions, balances, payment history, and compliance status. The accounts resource is the canonical entity returned by the API; it maps to the underlying customers table with enriched fields.

---

Account object

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "tenant_id": null,
  "contact_email": "[email protected]",
  "display_name": "Acme Corp",
  "country_code": "US",
  "kyb_status": "active",
  "api_tier": "direct",
  "metadata": {},
  "parent_platform_account_id": null,
  "created_at": "2026-06-08T00:00:00Z",
  "updated_at": "2026-06-08T00:00:00Z"
}

Field	Type	Description
id	uuid	Account UUID.
tenant_id	uuid | null	Tenant the account belongs to.
contact_email	string	Primary contact email.
display_name	string	Human-readable account name.
country_code	string	ISO 3166-1 alpha-2 country code.
kyb_status	string	pending, active, or rejected.
api_tier	string	direct or platform_ready.
metadata	object	Caller-defined key-value pairs.
parent_platform_account_id	uuid | null	Set when this is a managed sub-account.

---

POST /v1/accounts — Create account

Creates a new account. No authentication required for basic creation.

For platform flows, pass ?acting_as=<platform_account_id> to create a managed sub-account. Requires a JWT with api_tier=platform_ready.

POST /v1/accounts
Content-Type: application/json
Idempotency-Key: account-acme-001

{
  "contact_email": "[email protected]",
  "display_name": "Acme Corp",
  "country_code": "US",
  "metadata": {
    "erp_id": "ACC-1042"
  }
}

Platform sub-account creation

POST /v1/accounts?acting_as=<platform-uuid>
Authorization: Bearer <jwt-with-platform_ready>
Content-Type: application/json
Idempotency-Key: subaccount-merchant-001

This creates a managed account linked to the platform. The link is stored as a platform_permissions row.

Response (201 Created)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "contact_email": "[email protected]",
  "display_name": "Acme Corp",
  "country_code": "US",
  "kyb_status": "pending",
  "api_tier": "direct",
  "metadata": { "erp_id": "ACC-1042" },
  "created_at": "2026-06-08T00:00:00Z",
  "updated_at": "2026-06-08T00:00:00Z"
}

---

GET /v1/accounts/me — Caller's account

Returns the account associated with the calling credential.

Auth: Elevated — JWT (aud=internal or aud=admin) or master key only.

GET /v1/accounts/me
Authorization: Bearer <token>

---

GET /v1/accounts/me/balance — Balance

Returns the caller's balance breakdown by currency.

Auth: Elevated — JWT or master key only.

GET /v1/accounts/me/balance
Authorization: Bearer <token>

Response (200 OK)

{
  "totals": [
    { "currency": "USD",  "amount": "1000.00", "available": "1000.00", "pending": "0.00" },
    { "currency": "USDC", "amount": "50.00",   "available": "50.00",   "pending": "0.00" }
  ]
}

---

GET /v1/accounts/me/vibans — Virtual IBANs

Returns the caller's virtual IBANs with bank routing details.

Auth: Elevated — JWT or master key only.

GET /v1/accounts/me/vibans
Authorization: Bearer <token>

---

GET /v1/accounts — List accounts

Lists accounts visible to the caller. Supports filtering by tenant_id or managed_by (platform accounts only).

Auth: Elevated — JWT or master key only.

GET /v1/accounts?limit=50&offset=0
Authorization: Bearer <token>

Query parameters:

Param	Type	Description
tenant_id	uuid	Filter by tenant.
managed_by	uuid	List managed sub-accounts for a platform account.
limit	integer	Max rows (default 50).
offset	integer	Pagination offset.

---

GET /v1/accounts/{id} — Get account

Retrieve a single account by UUID.

Auth: Elevated — JWT or master key only.

GET /v1/accounts/3fa85f64-5717-4562-b3fc-2c963f66afa6
Authorization: Bearer <token>

---

Account KYB status

Status	Meaning
pending	Account created but KYB verification not yet complete.
active	KYB verified — account can transact.
rejected	KYB rejected — account cannot transact.

Accounts with kyb_status != active cannot initiate payments. The api_tier claim on the JWT controls whether an account can create managed sub-accounts.

---

API tier

Value	Meaning
direct	Single-account flows only.
platform_ready	Can create and manage sub-accounts via ?acting_as=.

Platform tier is granted by CashXChain after your platform integration is approved.

---

Account types

Type	Description
Business account	A company using CashXChain directly.
Platform account	A platform embedding CashXChain for its customers. Requires api_tier=platform_ready.
Managed sub-account	A customer account created by a platform via ?acting_as=. Has a parent_platform_account_id.