Account Details

Account details are the banking coordinates Nuvion provisions for an account. Share them with payers to receive funds — routing number and account number for USD, IBAN and BIC for EUR, sort code and account number for GBP, and wallet addresses for stablecoins.

The Account Details object

string

Unique identifier for this set of account details.

string

The ID of the entity that owns the account.

string

The ID of the account these details belong to.

string

Bank account number or IBAN for fiat accounts. Wallet address for stablecoin accounts.

object

The institution or network that issued these details.

Show issuer fields

string

Institution name (e.g. Lead Bank) or network name (e.g. Ethereum Mainnet).

string

Routing number, BIC, sort code, or chain code depending on the currency and asset_type.

string

The blockchain the wallet address is provisioned on. Stablecoin accounts only. One of eth, base, matic, or sol.

array

The stablecoin assets that can be received at this address. Stablecoin accounts only. Always ["USDC", "USDT"].

string

active — ready to receive funds. pending — being provisioned (stablecoin accounts only, while the wallet address is generated on-chain).

number

Number of days until these details expire and deactivate. Null if no expiry is set.

number

Unix timestamp in milliseconds when the account details were created.

number

Unix timestamp in milliseconds when the account details were last updated.

{
  "id": "01HXYZ9012IJKL",
  "entity_id": "01HXYZ1234ABCD",
  "account_id": "01HXYZ5678EFGH",
  "account_number": "4561237890",
  "issuer": {
    "name": "Lead Bank",
    "code": "021000021"
  },
  "status": "active",
  "terminate_after": null,
  "created": 1735725600000,
  "updated": 1735725600000
}

{
  "id": "01HXYZ9012MNOP",
  "entity_id": "01HXYZ1234ABCD",
  "account_id": "01HXYZ5678EFGH",
  "chain": "eth",
  "account_number": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "supported_assets": ["USDC", "USDT"],
  "issuer": {
    "name": "Ethereum Mainnet",
    "code": "ETH_MAINNET"
  },
  "status": "pending",
  "terminate_after": null,
  "created": 1735725600000,
  "updated": 1735725600000
}

Create account details

Provision banking coordinates or a wallet address for an account. The type of details provisioned depends on currency.

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

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

Request parameters

string

required

The ID of the account to provision details for.

string

The blockchain to provision the wallet on. One of eth, base, matic, or sol.

number

Number of days after which these details expire and deactivate automatically. Omit for permanent details.

string

Fiat only. Override the default banking provider. Omit to use the Nuvion default for the account currency.

Response

Returns the created account details object. Fiat details are active immediately. Stablecoin details start as pending.

Response

{
  "id": "01HXYZ9012IJKL",
  "entity_id": "01HXYZ1234ABCD",
  "account_id": "01HXYZ5678EFGH",
  "account_number": "4561237890",
  "issuer": {
    "name": "Lead Bank",
    "code": "021000021"
  },
  "status": "active",
  "terminate_after": null,
  "created": 1735725600000,
  "updated": 1735725600000
}

Stablecoin details are created with status: "pending" while the wallet address is provisioned on-chain. Listen for the account_details.created webhook to confirm the address is ready before sharing it with payers.

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

Identifiers returned by currency

The fields populated in account_number and issuer.code depend on the account currency.

Currency	Identifiers
USD	Account number, routing number
EUR	IBAN, BIC
GBP	Account number, sort code
CAD	Account number, institution number, transit number
AED	Account number, IBAN
NGN	Account number
ZAR	Account number, branch code

List account details

Returns a paginated list of account details records.

curl "https://api.nuvion.dev/account-details?account_id=01HXYZ5678EFGH" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Request parameters

string

Filter by account ID. Required when authenticating with an API key.

integer

Number of results to return. Between 1 and 100. Defaults to 20.

string

Pagination cursor from a previous response. Omit for the first page.

Response

{
  "data": [
    {
      "id": "01HXYZ9012IJKL",
      "entity_id": "01HXYZ1234ABCD",
      "account_id": "01HXYZ5678EFGH",
      "account_number": "4561237890",
      "issuer": {
        "name": "Lead Bank",
        "code": "021000021"
      },
      "status": "active",
      "terminate_after": null,
      "created": 1735725600000,
      "updated": 1735725600000
    }
  ],
  "meta": {
    "pagination": {
      "has_next": false,
      "has_previous": false,
      "next_cursor": null,
      "previous_cursor": null,
      "total_count": 1
    }
  }
}

Get account details

Retrieves a single set of account details by ID.

curl "https://api.nuvion.dev/account-details/01HXYZ9012IJKL" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Request parameters

string

required

The ID of the account details record to retrieve.

Response

Returns the account details object.

Response

{
  "id": "01HXYZ9012IJKL",
  "entity_id": "01HXYZ1234ABCD",
  "account_id": "01HXYZ5678EFGH",
  "account_number": "4561237890",
  "issuer": {
    "name": "Lead Bank",
    "code": "021000021"
  },
  "status": "active",
  "terminate_after": null,
  "created": 1735725600000,
  "updated": 1735725600000
}

Expiring account details

Pass terminate_after on creation to set an expiry. Details deactivate automatically after that many days — no further action is needed. Expired details stop accepting inbound funds. Use cases for expiring details include temporary collection accounts, one-off payout flows, and time-limited receiving addresses where you want to ensure funds aren’t received outside a defined window.

​The Account Details object

​Create account details

​Request parameters

​Response

​Identifiers returned by currency

​List account details

​Request parameters

​Response

​Get account details

​Request parameters

​Response

​Expiring account details

The Account Details object

Create account details

Request parameters

Response

Identifiers returned by currency

List account details

Request parameters

Response

Get account details

Request parameters

Response

Expiring account details