Accounts

An account is a currency-denominated balance container belonging to an entity. Before an entity can hold or move money, they need at least one account. Accounts can receive funds via bank transfer, be debited for payouts, and be assigned account details — the banking coordinates that counterparties use to send funds.

An entity must have approved status before accounts can be created for them. See Entities for the onboarding flow.

Account types

Type	Description
`checking`	General-purpose account for everyday transactions — receiving payments, sending payouts, and holding balances
`debit`	An account linked to a debit instrument for card-based spending
`operational`	An account used for platform-level operational funds, separate from entity balances
`safeguard`	A segregated account used to safeguard funds in accordance with regulatory requirements

The first account created for an entity automatically becomes their default account.

The account object

{
  "id": "acc_01HXYZ5678EFGH",
  "entity_id": "ent_01HXYZ1234ABCD",
  "type": "checking",
  "currency": "USD",
  "display_name": "Main USD Account",
  "nuvion_ban": "NVN0000012345",
  "balance": {
    "available": 10000,
    "current": 10000
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}

string

Unique identifier for the account. ULID format.

string

The ID of the entity this account belongs to.

string

The account type. One of checking, debit, operational, safeguard.

string

ISO 4217 currency code. Fiat account: USD, GBP, EUR Stablecoin account: USC, RLD, UST

string

A human-readable label for the account.

string

Nuvion’s internal bank account number for this account. Used for internal routing.

object

The account’s current balance.

Show balance fields

number

Funds available for use. This excludes any amounts held pending settlement or compliance review.

number

Total balance including pending amounts not yet available.

object

Optional key-value metadata you can attach to an account for your own reference.

number

Unix timestamp in milliseconds of when the account was created.

number

Unix timestamp in milliseconds of the last update to the account.

Creating an account

curl -X POST https://api.nuvion.dev/accounts \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "checking",
    "currency": "USD",
    "display_name": "Main USD Account",
    "meta": {
      "internal_ref": "acc-primary"
    }
  }'

string

required

The account type. One of checking, debit, operational, safeguard.

string

ISO 4217 currency code. Fiat account: USD, GBP, EUR Stablecoin account: USC, RLD, UST

string

required

A human-readable label for the account.

object

Optional key-value metadata to attach to the account.

Account details

Account details are the banking coordinates that allow counterparties to send funds into an account. The fields returned depend on the account’s currency.

Currency	Details provided
`USD`	Account number, routing number, SWIFT code
`EUR`	IBAN, BIC
`GBP`	Account number, sort code

Creating account details

curl -X POST https://api.nuvion.dev/account-details \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01HXYZ5678EFGH",
  }'

string

required

The ID of the account to generate banking coordinates for.

number

Number of days after which the account details expire. Omit for permanent details.

Account details object

{
  "id": "acd_01HXYZ9012IJKL",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "account_number": "4561237890",
  "issuer": {
    "name": "Lead Bank",
    "code": "021000021"
  },
  "status": "active",
  "created": 1735725600000,
  "updated": 1735725600000
}

{
  "id": "acd_01HXYZ9012IJKL",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "account_number": "DE89370400440532013000",
  "issuer": {
    "name": "Nuvion EU",
    "code": "NUVIDEF1"
  },
  "status": "active",
  "created": 1735725600000,
  "updated": 1735725600000
}

{
  "id": "acd_01HXYZ9012IJKL",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "account_number": "12345678",
  "issuer": {
    "name": "Nuvion UK",
    "code": "20-00-00"
  },
  "status": "active",
  "created": 1735725600000,
  "updated": 1735725600000
}

string

Unique identifier for the account details. ULID format.

string

The ID of the entity that owns the account.

string

The ID of the account these details belong to.

string

The bank account number or IBAN, depending on currency.

object

The financial institution that issued the account details.

Show issuer fields

string

Name of the issuing financial institution.

string

Routing number (USD), BIC (EUR), or sort code (GBP).

string

Current status of the account details. active when ready to receive funds.

number

Unix timestamp in milliseconds of when the account details were created.

number

Unix timestamp in milliseconds of the last update.

Account details are persistent. Create them once per account and store them — you don’t need to regenerate them for each transaction.

Balances

An account has two balance fields:

Field	Description
`balance.available`	Funds the entity can use immediately — for payouts, FX, or stablecoin transfers
`balance.current`	Total balance including amounts pending settlement or under compliance review

Always use balance.available when checking whether an entity has sufficient funds for a transaction.

All balance amounts are in the smallest currency unit — cents for USD and EUR, pence for GBP. A balance.available of 10000 is $100.00 USD.

Webhooks

Account webhook event types and payload schemas are pending confirmation with engineering. This section will be updated.

What’s next

Accept a payment

Receive funds into an account via bank transfer or card.

Send a payout

Send funds from an account to any bank account globally.

Accounts API reference

Full endpoint documentation for creating and managing accounts.

Get Started

Core Concepts

Webhooks

Guides

Account types

The account object

Creating an account

Account details

Creating account details

Account details object

Balances

Webhooks

What’s next

Accept a payment

Send a payout

Accounts API reference

​Account types

​The account object

​Creating an account

​Account details

​Creating account details

​Account details object

​Balances

​Webhooks

​What’s next

Accept a payment

Send a payout

Accounts API reference

Account types

The account object

Creating an account

Account details

Creating account details

Account details object

Balances

Webhooks

What’s next