Account Details

Account details are the banking coordinates Nuvion provisions for an account, shared with payers to receive funds. See Account Details for supported currencies and chains, and the inflows.completed webhook.

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.

object

Summary of the account these details belong to.

Show account_summary fields

string

The account’s ID. Matches account_id.

string

Account type. One of checking, debit, operational, or safeguard.

string

ISO 4217 currency code of the account.

string

Human-readable label for the account.

string

The kind of account details. fiat for bank-routing details, stablecoin for blockchain wallet addresses.

string

ISO 4217 currency code the account details are denominated in. USC (USDC) or UST (USDT) for stablecoin account details.

string

Name of the account holder the funds are ultimately credited to.

string

Display name for the account details.

string

The provisioned account identifier: a bank account number for fiat account details, or a wallet address for stablecoin account details. For fiat account details, absent while status is pending.

string

IBAN for the account details, when applicable. Present alongside account_number for currencies that use IBANs (e.g. GBP, EUR).

string

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

object

The institution or network that issued the account details.

Show issuer fields

string

Internal identifier for the issuing institution or network.

string

Name of the issuing institution or network.

string

Alternate label for the issuer, alongside name.

string

A code identifying the issuer within scheme. Format and meaning vary by provider.

string

The naming scheme code belongs to (e.g. a central bank’s bank-code scheme, or Nuvion’s own internal scheme).

object

Additional provider-specific banking details for the issuer. Populated fields vary by provider.

Show issuer.meta fields

string

Name of the issuing bank, when applicable.

string

Postal address of the issuing bank.

string

SWIFT/BIC code for the issuing bank, when applicable.

string

US ACH/wire routing number for the issuing bank, when applicable.

string

Sort code for the issuing bank, when applicable.

string

Basic Bank Account Number for the issuing bank, when applicable.

string

The issuing bank’s own reference for the account, when applicable.

string

Provider-specific receiver identifier used for reconciliation, when applicable.

string

Identifier for the provider’s own parent account backing these account details.

string

Identifier for the provider’s virtual account backing these account details, when applicable.

string

Tracking reference from the provider’s account-creation request.

object

Capabilities enabled on these account details.

Show config fields

boolean

Whether funds can be sent out through these account details.

boolean

Whether funds can be received through these account details.

array

Counterparty IDs allowed to receive outflows. Empty means no restriction.

array

Counterparty IDs allowed to send inflows. Empty means no restriction.

string

Current status of the account details. pending while being provisioned, active when ready to receive funds.

string

Human-readable explanation of the current status.

string

US ACH/wire routing number. Present for USD account details issued via routing-number-based providers.

number

0 if the account details are active. Non-zero if they have been deleted.

object

Key-value metadata attached to the account details.

number

Unix timestamp in milliseconds when the account details were created.

number

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

{
  "status": "success",
  "message": "Account detail created successfully",
  "data": {
    "account_details": {
      "id": "01HXYZ0048ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "account_id": "01HXYZ0049ABCDEFGHJKMNPQRS",
      "issuer": {
        "name": "NUV",
        "short_name": "NUV",
        "code": "NUV"
      },
      "config": {
        "outflow_enabled": true,
        "inflow_enabled": true,
        "outflow_allowed_counterparties": [],
        "inflow_allowed_counterparties": []
      },
      "status": "pending",
      "asset_type": "fiat",
      "beneficiary_name": "John Doe",
      "currency": "USD",
      "created": 1787286545993,
      "updated": 1787286545993,
      "deleted": 0,
      "name": "John Doe"
    }
  }
}

{
  "status": "success",
  "message": "Account detail retrieved successfully",
  "data": {
    "account_detail": {
      "id": "01HXYZ0050ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "account_id": "01HXYZ0051ABCDEFGHJKMNPQRS",
      "issuer": {
        "name": "Thornbury Bank",
        "code": "040004",
        "scheme": "sort_code",
        "meta": {
          "parent_account_id": "00000000-0000-0000-0000-000000000004",
          "virtual_account_id": "00000000-0000-0000-0000-000000000005",
          "bban": "THRN04000400000001",
          "bank_address": "1 Example Street, London, England EC1N 8DX",
          "swift_code": "THRNGB22XXX"
        },
        "id": "000000000000000000000004"
      },
      "config": {
        "outflow_enabled": true,
        "inflow_enabled": true,
        "outflow_allowed_counterparties": [],
        "inflow_allowed_counterparties": []
      },
      "status": "active",
      "asset_type": "fiat",
      "beneficiary_name": "John Doe",
      "currency": "GBP",
      "created": 1787230804905,
      "updated": 1787230806170,
      "deleted": 0,
      "account_number": "00000001",
      "iban": "GB00THRN04000400000001",
      "status_reason": "Account request approved"
    }
  }
}

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

Create account details

POST /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": "01HXYZ0049ABCDEFGHJKMNPQRS"
  }'

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

Request parameters

string

required

The ID of the account to provision details for.

string

The entity that owns the account. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

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

Response

Returns the account details object above. Provisioning can be asynchronous for both fiat and stablecoin account details: the response returns status: "pending" until provisioning completes, then active.

Response

{
  "status": "success",
  "message": "Account detail created successfully",
  "data": {
    "account_details": {
      "id": "01HXYZ0048ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "account_id": "01HXYZ0049ABCDEFGHJKMNPQRS",
      "issuer": {
        "name": "NUV",
        "short_name": "NUV",
        "code": "NUV"
      },
      "config": {
        "outflow_enabled": true,
        "inflow_enabled": true,
        "outflow_allowed_counterparties": [],
        "inflow_allowed_counterparties": []
      },
      "status": "pending",
      "asset_type": "fiat",
      "beneficiary_name": "John Doe",
      "currency": "USD",
      "created": 1787286545993,
      "updated": 1787286545993,
      "deleted": 0,
      "name": "John Doe"
    }
  }
}

Listen for the account_details.updated webhook to know when status moves from pending to active. Stablecoin details are pending while the wallet address is confirmed on-chain. See Account Details for which identifiers are returned per currency.

List account details

GET /account-details Returns a paginated list of account details records.

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

Query parameters

string

Filter by account ID.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

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

Returns a paginated list of account details objects.

Response

{
  "status": "success",
  "message": "Account details retrieved successfully",
  "data": {
    "data": [
      {
        "id": "01HXYZ0050ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "account_id": "01HXYZ0051ABCDEFGHJKMNPQRS",
        "issuer": {
          "name": "Thornbury Bank",
          "code": "040004",
          "scheme": "sort_code",
          "meta": {
            "parent_account_id": "00000000-0000-0000-0000-000000000004",
            "virtual_account_id": "00000000-0000-0000-0000-000000000005",
            "bban": "THRN04000400000001",
            "bank_address": "1 Example Street, London, England EC1N 8DX",
            "swift_code": "THRNGB22XXX"
          },
          "id": "000000000000000000000004"
        },
        "config": {
          "outflow_enabled": true,
          "inflow_enabled": true,
          "outflow_allowed_counterparties": [],
          "inflow_allowed_counterparties": []
        },
        "status": "active",
        "asset_type": "fiat",
        "beneficiary_name": "John Doe",
        "currency": "GBP",
        "created": 1787230804905,
        "updated": 1787230806170,
        "deleted": 0,
        "account_number": "00000001",
        "iban": "GB00THRN04000400000001",
        "status_reason": "Account request approved",
        "account_summary": {
          "id": "01HXYZ0051ABCDEFGHJKMNPQRS",
          "type": "checking",
          "currency": "GBP",
          "display_name": "Main GBP Account"
        }
      }
    ],
    "meta": {
      "pagination": {
        "limit": 20,
        "total_count": 1,
        "has_next": false,
        "has_previous": false,
        "next_cursor": null,
        "previous_cursor": null
      },
      "filters_applied": {
        "entity_id": null,
        "account_id": "01HXYZ0051ABCDEFGHJKMNPQRS",
        "sort": "created_desc"
      }
    }
  }
}

Get account details

GET /account-details/{account_details_id} Retrieves a single set of account details by ID.

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

Path parameters

string

required

The ID of the account details record to retrieve.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Response

Returns the account details, along with the owning entity, the owning account, and usage statistics.

Unlike the create and list responses, the account details object here is keyed as account_detail (singular), not account_details.

object

The Account Details object above.

object

Summary of the entity that owns the account.

Show entity fields

string

The entity’s ID.

string

Display name for the entity.

string

individual or business.

string

The entity’s review state. See Entity statuses.

object

The account these details belong to. See The Account object for the full field list.

object

Transaction activity on this account.

Show usage_statistics fields

number

Total number of transactions on the account.

number

Number of transactions that completed successfully.

number

Number of transactions that failed.

number

Unix timestamp in milliseconds of the most recent transaction.

array

Inflow and outflow volume, broken down by currency.

Show total_volume_by_currency fields

string

ISO 4217 currency code.

number

Total inflow volume in this currency, in major units.

number

Total outflow volume in this currency, in major units.

Response

{
  "status": "success",
  "message": "Account detail retrieved successfully",
  "data": {
    "account_detail": {
      "id": "01HXYZ0050ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "account_id": "01HXYZ0051ABCDEFGHJKMNPQRS",
      "issuer": {
        "name": "Thornbury Bank",
        "code": "040004",
        "scheme": "sort_code",
        "meta": {
          "parent_account_id": "00000000-0000-0000-0000-000000000004",
          "virtual_account_id": "00000000-0000-0000-0000-000000000005",
          "bban": "THRN04000400000001",
          "bank_address": "1 Example Street, London, England EC1N 8DX",
          "swift_code": "THRNGB22XXX"
        },
        "id": "000000000000000000000004"
      },
      "config": {
        "outflow_enabled": true,
        "inflow_enabled": true,
        "outflow_allowed_counterparties": [],
        "inflow_allowed_counterparties": []
      },
      "status": "active",
      "asset_type": "fiat",
      "beneficiary_name": "John Doe",
      "currency": "GBP",
      "created": 1787230804905,
      "updated": 1787230806170,
      "deleted": 0,
      "account_number": "00000001",
      "iban": "GB00THRN04000400000001",
      "status_reason": "Account request approved"
    },
    "entity": {
      "id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "name": "Acme Corp",
      "type": "business",
      "verification_status": "approved"
    },
    "account": {
      "id": "01HXYZ0051ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "type": "checking",
      "currency": "GBP",
      "display_name": "Main GBP Account",
      "config": {
        "overdraft_limit": 0,
        "balance_next_refresh": 0,
        "is_overdraftable": false,
        "balance_refresh_interval": 15
      },
      "balance": {
        "available": 0,
        "current": 0,
        "overdraft_used": 0
      },
      "maintenance_fee_opted_out": false,
      "created": 1787230774701,
      "updated": 1787230775367,
      "deleted": 0,
      "nuvion_ban": "0010650099",
      "balance_id": "100000000000000000000000000000001"
    },
    "usage_statistics": {
      "total_transactions": 127,
      "successful_transactions": 124,
      "failed_transactions": 3,
      "last_transaction_date": 1735689600000,
      "total_volume_by_currency": [
        {
          "currency": "USD",
          "inflow_volume": 250000.75,
          "outflow_volume": 180000.5
        }
      ]
    }
  }
}

​The Account Details object

​Create account details

​Request parameters

​Response

​List account details

​Query parameters

​Response

​Get account details

​Path parameters

​Query parameters

​Response

The Account Details object

Create account details

Request parameters

Response

List account details

Query parameters

Response

Get account details

Path parameters

Query parameters

Response