Quickstart

You’ll need a Nuvion sandbox API key to follow this guide. Create an account to get yours.

Before you begin

Every request to the Nuvion API requires these headers:

Header	Value
`Authorization`	`Bearer NUVION_API_KEY`
`Content-Type`	`application/json`

Set your API key as an environment variable so you don’t repeat yourself:

export NUVION_API_KEY=nuvion_api_key

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": "01HXYZ5678EFGH",
  "entity_id": "01HXYZ1234ABCD",
  "type": "checking",
  "currency": "USD",
  "display_name": "Main USD Account",
  "nuvion_ban": "NVN0000012345",
  "balance": {
    "available": 0,
    "current": 0
  },
  "created": 1735725600000,
  "updated": 1735725600000
}

Step 3: Register a counterparty

A counterparty represents a payout recipient — a person or business you send funds to. Counterparties hold identity information. Payment routing details (bank account numbers, wallet addresses) are stored separately as payment details attached to the counterparty.

  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "profile": {
      "first_name": "Jane",
      "last_name": "Smith",
      "relationship": "vendor",
      "email": "jane.smith@example.com",
      "address": {
        "line1": "123 Main St",
        "city": "Austin",
        "state_or_province": "TX",
        "postal_code": "78701",
        "country": "US"
      }
    }
  }'

Step 4: 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": "01HXYZ5678EFGH",
    "asset_type": "fiat"
  }'

{
  "id": "acd_01HXYZ9012IJKL",
  "entity_id": "01HXYZ1234ABCD",
  "account_id": "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: Initiate Transfer

In sandbox, use the /transfers endpoint to simulate transfers. The sandbox environment lets you test transfers, payouts, accept payments and other flows without using real funds.

-H "Authorization: Bearer $NUVION_API_KEY" \
-H "Content-Type: application/json" \   
-d '{
    "currency": "USD",
    "amount": 10000,
    "account_id": "01KCKRJJH6A3SJMAXBB737K5NP",
    "narration": "Payment for services rendered",
    "payment_detail_id": "01KQHBQQW1GR5PBH16BY0T56PP",
    "payment_type": "bank-transfer",
    "counterparty_id": "01KQESEEKSRKEKMACFX5HN0Q58",
    "unique_reference": "INV-12345"
}'

All amounts in the Nuvion API are in the smallest currency unit. 10000 is $100.00 USD.

Step 5: Retrieve account

Retrieve the account to confirm account data.

curl https://api.nuvion.dev/accounts?entity_id=01KCKRJJH6A3SJMAXBB737K5NP \
  -H "Authorization: Bearer $NUVION_API_KEY"

{
      "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
      "type": "checking",
      "currency": "USD",
      "display_name": "USD Test2 account",
      "config": {
          "overdraft_limit": 0,
          "is_overdraftable": false
      },
      "nuvion_ban": "0000629000",
      "balance": {
          "current": 30000000,
          "available": 30000000,
          "overdraft_used": 0
      },
      "created": 1778239923594,
      "updated": 1779101523841,
      "id": "01KR3NQSCAY9SC8WVKWAX2XJAB",
      "status": "active"
},

Your entity now has an account with banking coordinates. You’re ready to start building.

Get Started

Core Concepts

Webhooks

Guides

Before you begin

Step 1: Create an entity

Step 2: Create an account

Step 3: Register a counterparty

Step 4: Create account details

Step 4: Initiate Transfer

Step 5: Retrieve account

What’s next

Accept a payment

Send a payout

​Before you begin

​Step 1: Create an entity

​Step 2: Create an account

​Step 3: Register a counterparty

​Step 4: Create account details

​Step 4: Initiate Transfer

​Step 5: Retrieve account

​What’s next

Accept a payment

Send a payout

Before you begin

Step 1: Create an entity

Step 2: Create an account

Step 3: Register a counterparty

Step 4: Create account details

Step 4: Initiate Transfer

Step 5: Retrieve account

What’s next