> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuvion.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounts

> Accounts hold balances for an entity. Each account is denominated in a single currency and can be funded, debited, and assigned banking coordinates for receiving funds.

An account is a currency-denominated balance container belonging to an entity. Before an entity can hold or move money, they need at least one account. Accounts can receive funds via bank transfer, be debited for payouts, and be assigned account details — the banking coordinates that counterparties use to send funds.

<Note>
  An entity must have `approved` status before accounts can be created for them. See [Entities](/core-concepts/entities) for the onboarding flow.
</Note>

***

## Account types

| Type          | Description                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| `checking`    | General-purpose account for everyday transactions — receiving payments, sending payouts, and holding balances |
| `debit`       | An account linked to a debit instrument for card-based spending                                               |
| `operational` | An account used for platform-level operational funds, separate from entity balances                           |
| `safeguard`   | A segregated account used to safeguard funds in accordance with regulatory requirements                       |

<Tip>
  The first account created for an entity automatically becomes their default account.
</Tip>

***

## The account object

```json theme={null}
{
  "id": "acc_01HXYZ5678EFGH",
  "entity_id": "ent_01HXYZ1234ABCD",
  "type": "checking",
  "currency": "USD",
  "display_name": "Main USD Account",
  "nuvion_ban": "NVN0000012345",
  "balance": {
    "available": 10000,
    "current": 10000
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}
```

<ResponseField name="id" type="string">
  Unique identifier for the account. ULID format.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The ID of the entity this account belongs to.
</ResponseField>

<ResponseField name="type" type="string">
  The account type. One of `checking`, `debit`, `operational`, `safeguard`.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code.
  Fiat account: `USD`, `GBP`, `EUR`
  Stablecoin account: `USC`, `RLD`, `UST`
</ResponseField>

<ResponseField name="display_name" type="string">
  A human-readable label for the account.
</ResponseField>

<ResponseField name="nuvion_ban" type="string">
  Nuvion's internal bank account number for this account. Used for internal routing.
</ResponseField>

<ResponseField name="balance" type="object">
  The account's current balance.

  <Expandable title="balance fields">
    <ResponseField name="available" type="number">
      Funds available for use. This excludes any amounts held pending settlement or compliance review.
    </ResponseField>

    <ResponseField name="current" type="number">
      Total balance including pending amounts not yet available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Optional key-value metadata you can attach to an account for your own reference.
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp in milliseconds of when the account was created.
</ResponseField>

<ResponseField name="updated" type="number">
  Unix timestamp in milliseconds of the last update to the account.
</ResponseField>

***

## Creating an account

<CodeGroup>
  ```bash curl theme={null}
  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",
      "meta": {
        "internal_ref": "acc-primary"
      }
    }'
  ```
</CodeGroup>

<ParamField body="type" type="string" required>
  The account type. One of `checking`, `debit`, `operational`, `safeguard`.
</ParamField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code.
  Fiat account: `USD`, `GBP`, `EUR`
  Stablecoin account: `USC`, `RLD`, `UST`
</ResponseField>

<ParamField body="display_name" type="string" required>
  A human-readable label for the account.
</ParamField>

<ParamField body="meta" type="object">
  Optional key-value metadata to attach to the account.
</ParamField>

***

## Account details

Account details are the banking coordinates that allow counterparties to send funds into an account. The fields returned depend on the account's currency.

| Currency | Details provided                           |
| -------- | ------------------------------------------ |
| `USD`    | Account number, routing number, SWIFT code |
| `EUR`    | IBAN, BIC                                  |
| `GBP`    | Account number, sort code                  |

### Creating account details

<CodeGroup>
  ```bash curl theme={null}
  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",
    }'
  ```
</CodeGroup>

<ParamField body="account_id" type="string" required>
  The ID of the account to generate banking coordinates for.
</ParamField>

<ParamField body="terminate_after" type="number">
  Number of days after which the account details expire. Omit for permanent details.
</ParamField>

### Account details object

<CodeGroup>
  ```json USD theme={null}
  {
    "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
  }
  ```

  ```json EUR theme={null}
  {
    "id": "acd_01HXYZ9012IJKL",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "account_number": "DE89370400440532013000",
    "issuer": {
      "name": "Nuvion EU",
      "code": "NUVIDEF1"
    },
    "status": "active",
    "created": 1735725600000,
    "updated": 1735725600000
  }
  ```

  ```json GBP theme={null}
  {
    "id": "acd_01HXYZ9012IJKL",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "account_number": "12345678",
    "issuer": {
      "name": "Nuvion UK",
      "code": "20-00-00"
    },
    "status": "active",
    "created": 1735725600000,
    "updated": 1735725600000
  }
  ```
</CodeGroup>

<ResponseField name="id" type="string">
  Unique identifier for the account details. ULID format.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The ID of the entity that owns the account.
</ResponseField>

<ResponseField name="account_id" type="string">
  The ID of the account these details belong to.
</ResponseField>

<ResponseField name="account_number" type="string">
  The bank account number or IBAN, depending on currency.
</ResponseField>

<ResponseField name="issuer" type="object">
  The financial institution that issued the account details.

  <Expandable title="issuer fields">
    <ResponseField name="name" type="string">
      Name of the issuing financial institution.
    </ResponseField>

    <ResponseField name="code" type="string">
      Routing number (USD), BIC (EUR), or sort code (GBP).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the account details. `active` when ready to receive funds.
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp in milliseconds of when the account details were created.
</ResponseField>

<ResponseField name="updated" type="number">
  Unix timestamp in milliseconds of the last update.
</ResponseField>

<Tip>
  Account details are persistent. Create them once per account and store them — you don't need to regenerate them for each transaction.
</Tip>

***

## Balances

An account has two balance fields:

| Field               | Description                                                                     |
| ------------------- | ------------------------------------------------------------------------------- |
| `balance.available` | Funds the entity can use immediately — for payouts, FX, or stablecoin transfers |
| `balance.current`   | Total balance including amounts pending settlement or under compliance review   |

Always use `balance.available` when checking whether an entity has sufficient funds for a transaction.

<Note>
  All balance amounts are in the **smallest currency unit** — cents for USD and EUR, pence for GBP. A `balance.available` of `10000` is \$100.00 USD.
</Note>

***

## Webhooks

<Info>
  Account webhook event types and payload schemas are pending confirmation with engineering. This section will be updated.
</Info>

***

## What's next

<CardGroup cols={3}>
  <Card title="Accept a payment" icon="arrow-down-to-line" href="/guides/accept-a-payment">
    Receive funds into an account via bank transfer or card.
  </Card>

  <Card title="Send a payout" icon="arrow-up-from-line" href="/guides/send-a-payout">
    Send funds from an account to any bank account globally.
  </Card>

  <Card title="Accounts API reference" icon="code" href="/api-reference/accounts">
    Full endpoint documentation for creating and managing accounts.
  </Card>
</CardGroup>