Skip to main content
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

TypeDescription
checkingGeneral-purpose account for everyday transactions — receiving payments, sending payouts, and holding balances
debitAn account linked to a debit instrument for card-based spending
operationalAn account used for platform-level operational funds, separate from entity balances
safeguardA 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
}
​
id
string
Unique identifier for the account. ULID format.
​
entity_id
string
The ID of the entity this account belongs to.
​
type
string
The account type. One of checking, debit, operational, safeguard.
​
currency
string
ISO 4217 three-letter currency code. e.g. USD, EUR, GBP.
​
display_name
string
A human-readable label for the account.
​
nuvion_ban
string
Nuvion’s internal bank account number for this account. Used for internal routing.
​
balance
object
The account’s current balance.
​
meta
object
Optional key-value metadata you can attach to an account for your own reference.
​
created
number
Unix timestamp in milliseconds of when the account was created.
​
updated
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"
    }
  }'
​
type
string
required
The account type. One of checking, debit, operational, safeguard.
​
currency
string
required
ISO 4217 three-letter currency code. Supported values: USD, EUR, GBP.
​
display_name
string
required
A human-readable label for the account.
​
meta
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.
CurrencyDetails provided
USDAccount number, routing number, SWIFT code
EURIBAN, BIC
GBPAccount 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",
    "asset_type": "fiat"
  }'
​
account_id
string
required
The ID of the account to generate banking coordinates for.
​
asset_type
string
The type of asset for which to generate details. One of fiat (default) or stablecoin.
​
terminate_after
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
string
Unique identifier for the account details. ULID format.
​
entity_id
string
The ID of the entity that owns the account.
​
account_id
string
The ID of the account these details belong to.
​
account_number
string
The bank account number or IBAN, depending on currency.
​
issuer
object
The financial institution that issued the account details.
​
status
string
Current status of the account details. active when ready to receive funds.
​
created
number
Unix timestamp in milliseconds of when the account details were created.
​
updated
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:
FieldDescription
balance.availableFunds the entity can use immediately — for payouts, FX, or stablecoin transfers
balance.currentTotal 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.