Skip to main content
You’ll need a Nuvion sandbox API key to follow this guide. Sandbox keys start with nv_test_. Create an account to get yours.

​
Before you begin

Every request to the Nuvion API requires these headers:
HeaderValue
AuthorizationBearer nv_test_xxxxx
Content-Typeapplication/json
Set your API key as an environment variable so you don’t repeat yourself: 
export NUVION_API_KEY=nv_test_xxxxx

​
Step 1: Create an entity

An entity represents a person or business on your platform. All accounts and transactions belong to an entity. 
curl -X POST https://api.nuvion.dev/entities \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "first_name": "Alex",
    "last_name": "Johnson",
    "email": "alex.johnson@example.com",
    "country": "US"
  }'
A successful response returns an entity object. Save the id — you’ll need it in the next step. 
{
  "id": "ent_01HXYZ1234ABCD",
  "object": "entity",
  "type": "individual",
  "first_name": "Alex",
  "last_name": "Johnson",
  "email": "alex.johnson@example.com",
  "country": "US",
  "status": "active",
  "created_at": "2026-01-01T10:00:00Z"
}

​
Step 2: Create an account

Accounts hold balances. Each account is denominated in a single currency. An entity can have multiple accounts across different currencies. 
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"
  }'

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

​
Step 3: Create account details

Account details generate the banking coordinates for an account — routing numbers, IBANs, sort codes, and other identifiers depending on the currency and supported rails. These are what your entity shares with counterparties to receive funds. 
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"
  }'

{
  "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
}
Account details are persistent — you only need to create them once per account per rail. Store the returned details and reuse them.

​
Step 4: Fund the account (sandbox only)

In sandbox, use the test funding endpoint to simulate an inbound payment. This lets you test balance checks, payouts, and other flows without a real funding source. 
curl -X POST https://api.nuvion.dev/sandbox/accounts/acc_01HXYZ5678EFGH/fund \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "USD"
  }'
All amounts in the Nuvion API are in the smallest currency unit. 10000 is $100.00 USD.
{
  "id": "txn_01HXYZMNOP3456",
  "object": "transaction",
  "type": "credit",
  "account_id": "acc_01HXYZ5678EFGH",
  "amount": 10000,
  "currency": "USD",
  "status": "settled",
  "created_at": "2026-01-01T10:02:00Z"
}

​
Step 5: Check the balance

Retrieve the account to confirm the balance has been updated. 
curl https://api.nuvion.dev/accounts/acc_01HXYZ5678EFGH \
  -H "Authorization: Bearer $NUVION_API_KEY"

{
  "id": "acc_01HXYZ5678EFGH",
  "entity_id": "ent_01HXYZ1234ABCD",
  "type": "checking",
  "currency": "USD",
  "display_name": "Main USD Account",
  "balance": {
    "available": 10000,
    "current": 10000
  },
  "created": 1735725600000,
  "updated": 1735725600000
}
Your entity now has a funded account with banking coordinates. You’re ready to start building.

​
What’s next

Accept a payment

Receive funds from a bank transfer or card into a Nuvion account.

Send a payout

Send funds from an account to any bank account globally.