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`

This guide uses the sandbox base URL, https://api.nuvion.dev. No real funds move in sandbox. Set your API key as an environment variable so you don’t repeat yourself:

export NUVION_API_KEY=nv_live_sk_xxxxx

Step 1: Create an individual entity

An entity represents a person or business on your platform. Accounts, documents, and transfers all belong to an entity. Identity document metadata is required at creation. You’ll upload the actual files in the next step. Use POST /individual-entities.

curl -X POST https://api.nuvion.dev/individual-entities \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex Johnson",
    "person": {
      "first_name": "Alex",
      "last_name": "Johnson",
      "date_of_birth": "1990-04-12",
      "email": "alex.johnson@example.com",
      "nationality": "US",
      "gender": "m",
      "phonenumber": "+12125550198",
      "ssn": "123-45-6789"
    },
    "address": {
      "line_1": "210 West 77th Street",
      "city": "New York",
      "state": "New York",
      "postal_code": "10024",
      "country_code": "US"
    },
    "identification": {
      "document": {
        "type": "international_passport",
        "number": "P123456789",
        "issue_date": "2020-01-10",
        "expiry_date": "2030-01-09",
        "issuing_country": "US",
        "issuing_authority": "US Department of State"
      },
      "proof_of_address": {
        "type": "utility_bill"
      }
    }
  }'

Response

{
  "status": "success",
  "message": "Individual entity created successfully",
  "data": {
    "address": {
      "id": "01HXYZ1003ABCDEFGHJKMNPQRS",
      "line_1": "210 West 77th Street",
      "city": "New York",
      "state": "New York",
      "postal_code": "10024",
      "country_code": "US",
      "owner_id": "01HXYZ1002ABCDEFGHJKMNPQRS",
      "owner_type": "person",
      "created": 1787286430146,
      "updated": 1787286430146
    },
    "entity": {
      "id": "01HXYZ1001ABCDEFGHJKMNPQRS",
      "type": "individual",
      "status": "incomplete",
      "name": "Alex Johnson",
      "is_root": false,
      "parent_entity": "01HXYZ1099ABCDEFGHJKMNPQRS",
      "user_id": "01HXYZ1098ABCDEFGHJKMNPQRS",
      "creation_context": "api",
      "risk_level": "medium",
      "created": 1787286430214,
      "updated": 1787286430214
    },
    "person": {
      "id": "01HXYZ1002ABCDEFGHJKMNPQRS",
      "first_name": "Alex",
      "last_name": "Johnson",
      "date_of_birth": "1990-04-12",
      "email": "alex.johnson@example.com",
      "nationality": "US",
      "gender": "m",
      "is_pep": false,
      "status": "approved",
      "phonenumber": "+12125550198",
      "created": 1787286430079,
      "updated": 1787286430079
    },
    "identification": {
      "id": "01HXYZ1004ABCDEFGHJKMNPQRS",
      "person_id": "01HXYZ1002ABCDEFGHJKMNPQRS",
      "verification_status": "pending",
      "document": {
        "type": "international_passport",
        "number": "***6789",
        "issue_date": "2020-01-10",
        "expiry_date": "2030-01-09",
        "issuing_country": "US",
        "issuing_authority": "US Department of State",
        "verification_status": "pending"
      },
      "proof_of_address": {
        "type": "utility_bill",
        "verification_status": "pending"
      },
      "identity_numbers": [
        {
          "type": "SSN",
          "value": "***6789",
          "verification_status": "pending"
        }
      ],
      "created": 1787286430200,
      "updated": 1787286430200
    }
  }
}

Save data.entity.id and data.person.id. You’ll need both in the next step.

Step 2: Upload KYC documents

Two documents are required before the entity can be submitted for review: a government-issued ID and a proof of address. Use POST /documents, linking each file to the person via link_to_identity.person_id.

curl -X POST https://api.nuvion.dev/documents \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS",
    "key": "identity",
    "description": "Passport for Alex Johnson",
    "file": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
    "meta": {
      "file_type": "image/png"
    },
    "link_to_identity": {
      "person_id": "01HXYZ1002ABCDEFGHJKMNPQRS"
    }
  }'

curl -X POST https://api.nuvion.dev/documents \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS",
    "key": "proof_of_address",
    "description": "Utility bill for Alex Johnson",
    "file": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
    "meta": {
      "file_type": "image/png"
    },
    "link_to_identity": {
      "person_id": "01HXYZ1002ABCDEFGHJKMNPQRS"
    }
  }'

In sandbox, document content isn’t verified. Any valid base64-encoded file, like the tiny sample images above, is accepted. Both uploads are required before you can submit the entity for review.

Step 3: Submit for review

curl -X POST https://api.nuvion.dev/onboarding-submissions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS"
  }'

The entity’s status moves to pending. Review is automatic, often within seconds and typically no more than a few minutes. Nuvion fires the entities.updated webhook when the status changes to approved or rejected.

In production, listen for entities.updated instead of polling. For this quickstart, you can check status with GET /entities/{entity_id}. Accounts can only be created once status is approved.

Step 4: Create an account

Once the entity is approved, open an account to hold a balance. Use POST /accounts.

curl -X POST https://api.nuvion.dev/accounts \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS",
    "type": "checking",
    "currency": "EUR",
    "display_name": "Alex Main EUR"
  }'

Response

{
  "status": "success",
  "message": "Account created successfully",
  "data": {
    "account": {
      "id": "01HXYZ2001ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS",
      "type": "checking",
      "currency": "EUR",
      "display_name": "Alex Main EUR",
      "config": {
        "overdraft_limit": 0,
        "balance_next_refresh": 0,
        "is_overdraftable": false,
        "balance_refresh_interval": 15
      },
      "balance": {
        "available": 0,
        "current": 0,
        "overdraft_used": 0
      },
      "stablecoin_assets": {},
      "maintenance_fee_opted_out": false,
      "system_meta": {},
      "created": 1787610021768,
      "updated": 1787610021768,
      "deleted": 0,
      "meta": {},
      "nuvion_ban": "0010814002"
    },
    "entity_impact": {
      "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS",
      "total_accounts": 1,
      "account_type": [
        "checking"
      ],
      "default_account_set": true
    }
  }
}

Save data.account.id. You’ll use it as account_id in the remaining steps.

Step 5: Generate account details

Account details are the banking coordinates that others use to pay into this account. Provisioning starts as pending and finishes asynchronously. Poll GET /account-details/{id} or listen for the account_details.created webhook before sharing the details with payers. Use POST /account-details.

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

Response

{
  "status": "success",
  "message": "Account detail created successfully",
  "data": {
    "account_details": {
      "id": "01HXYZ2002ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS",
      "account_id": "01HXYZ2001ABCDEFGHJKMNPQRS",
      "issuer": {
        "code": "NUV",
        "name": "NUV",
        "short_name": "NUV"
      },
      "config": {
        "outflow_enabled": true,
        "inflow_enabled": true,
        "outflow_allowed_counterparties": [],
        "inflow_allowed_counterparties": []
      },
      "status": "pending",
      "asset_type": "fiat",
      "beneficiary_name": "Alex Johnson",
      "currency": "EUR",
      "created": 1787611058009,
      "updated": 1787611058009,
      "deleted": 0,
      "name": "Alex Johnson",
      "meta": {}
    }
  }
}

Account details are persistent. Create them once per account and reuse them for future payments.

Step 6: Fund the account

Your new EUR account has a 0 balance. Fund it via open banking: create a funding session, then complete the bank authentication at the returned checkout_url. Use POST /funding-sessions.

curl -X POST https://api.nuvion.dev/funding-sessions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 20000,
    "account_id": "01HXYZ2001ABCDEFGHJKMNPQRS",
    "funding_type": "open-banking",
    "redirect_url": "https://yourplatform.com/checkout/complete",
    "unique_reference": "FUND-2025-001",
    "narration": "Fund EUR account"
  }'

Response

{
  "status": "success",
  "message": "Funding session created successfully",
  "data": {
    "id": "01HXYZ2501ABCDEFGHJKMNPQRS",
    "status": "awaiting_user",
    "unique_reference": "FUND-2025-001",
    "currency": "EUR",
    "amount": 20000,
    "checkout_url": "https://app.nuvion.dev/checkout/01HXYZ2501ABCDEFGHJKMNPQRS",
    "expires_at": 1787612561023
  }
}

Open checkout_url in a browser and complete the sandbox bank authentication flow. Nuvion credits the account and fires funding_sessions.updated once the session reaches status: "settled".

Wait for funding_sessions.updated, or poll GET /funding-sessions/{id}, before initiating a transfer. Fund more than you intend to send. Transfers carry a fee on top of the amount, so funding the exact transfer amount can leave insufficient balance.available.

Step 7: Add a payout recipient

To send money out, register who you’re paying and their bank details. This is a two-call flow: create a counterparty, then attach their SEPA payment details. See Send a payout for every supported rail and corridor.

curl -X POST https://api.nuvion.dev/counterparties \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS",
    "profile": {
      "first_name": "Michael",
      "last_name": "Weber",
      "relationship": "vendor",
      "email": "michael.weber@example.com",
      "address": {
        "line1": "Hauptstr. 12",
        "city": "Berlin",
        "state_or_province": "Berlin",
        "postal_code": "10117",
        "country": "DE"
      }
    }
  }'

curl -X POST https://api.nuvion.dev/payment-details \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "bank-transfer",
    "currency": "EUR",
    "country": "DE",
    "account_holder_name": "Michael Weber",
    "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ3001ABCDEFGHJKMNPQRS",
    "iban": "DE89370400440532013000",
    "swift_bic": "COBADEFFXXX",
    "bank_name": "Commerzbank"
  }'

Save id from the counterparty response as counterparty_id, and id from the payment details response as payment_detail_id. You’ll need both for the transfer.

Step 8: Send a transfer

Use POST /transfers to move money from your funded EUR account to the recipient.

curl -X POST https://api.nuvion.dev/transfers \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS",
    "account_id": "01HXYZ2001ABCDEFGHJKMNPQRS",
    "payment_detail_id": "01HXYZ3002ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ3001ABCDEFGHJKMNPQRS",
    "amount": 10000,
    "currency": "EUR",
    "narration": "Invoice payment INV-2025-001",
    "payment_type": "bank-transfer",
    "unique_reference": "PAY-2025-001"
  }'

Response

{
  "status": "success",
  "message": "Transfer created successfully",
  "data": {
    "id": "01HXYZ4001ABCDEFGHJKMNPQRS",
    "amount": 10000,
    "currency": "EUR",
    "unique_reference": "PAY-2025-001",
    "counterparty_id": "01HXYZ3001ABCDEFGHJKMNPQRS",
    "account_id": "01HXYZ2001ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1001ABCDEFGHJKMNPQRS",
    "status": "pending",
    "status_reason": "awaiting_processing",
    "narration": "Invoice payment INV-2025-001",
    "type": "outflow",
    "payment_type": "bank-transfer",
    "applicable_fee": 50,
    "meta": {},
    "created": 1787415765559,
    "updated": 1787415765559
  }
}

All amounts are in the smallest currency unit. 10000 = €100.00 EUR.

You’ve created an entity, gotten it approved, opened and funded a EUR account, and sent a SEPA payout. You’re ready to build.

Get Started

Core Concepts

Webhooks

Guides

Before you begin

Step 1: Create an individual entity

Step 2: Upload KYC documents

Step 3: Submit for review

Step 4: Create an account

Step 5: Generate account details

Step 6: Fund the account

Step 7: Add a payout recipient

Step 8: Send a transfer

What’s next

Accept a payment

Send a payout

​Before you begin

​Step 1: Create an individual entity

​Step 2: Upload KYC documents

​Step 3: Submit for review

​Step 4: Create an account

​Step 5: Generate account details

​Step 6: Fund the account

​Step 7: Add a payout recipient

​Step 8: Send a transfer

​What’s next

Accept a payment

Send a payout

Before you begin

Step 1: Create an individual entity

Step 2: Upload KYC documents

Step 3: Submit for review

Step 4: Create an account

Step 5: Generate account details

Step 6: Fund the account

Step 7: Add a payout recipient

Step 8: Send a transfer

What’s next