> ## 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.

# Account Details

> External-facing identifiers that allow your account to send and receive funds on payment rails.

Account details are the banking coordinates provisioned by Nuvion for an account. They are what your entities share with counterparties to receive funds — routing numbers and account numbers for USD, IBANs and BICs for EUR, and wallet addresses for stablecoin rails.

Each account can have one active set of fiat account details and one per stablecoin chain. Once generated, account details are permanently bound to that account and cannot be reassigned.

<Note>
  An account must exist before account details can be created for it. See [Accounts](/core-concepts/accounts) for how to create an account.
</Note>

***

## Fiat account details

Fiat account details provision real banking coordinates. The identifiers returned depend on the account's currency:

| Currency | Identifiers provided                               |
| -------- | -------------------------------------------------- |
| `USD`    | Account number, routing number, SWIFT code         |
| `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                        |

### Creating fiat 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. See [Expiration](#expiration).
</ParamField>

<ParamField body="provider_id" type="string">
  Provider identifier for issuance. Omit to use Nuvion's default provider.
</ParamField>

### Fiat account details object

<CodeGroup>
  ```json USD theme={null}
  {
    "id": "acd_01HXYZ9012IJKL",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "asset_type": "fiat",
    "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 the account's 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>

***

## Stablecoin account details

Stablecoin account details provision a wallet address on a supported blockchain. The entity uses this address to receive stablecoin transfers — USDC and USDT are supported on all chains.

| Chain   | Network          | Address format |
| ------- | ---------------- | -------------- |
| `eth`   | Ethereum Mainnet | `0x...`        |
| `base`  | Base             | `0x...`        |
| `matic` | Polygon          | `0x...`        |
| `sol`   | Solana Mainnet   | Base58         |

### Creating stablecoin 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",
      "chain": "eth"
    }'
  ```
</CodeGroup>

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

<ParamField body="chain" type="string" required>
  The blockchain to provision the wallet address on. One of `eth`, `base`, `matic`, `sol`.
</ParamField>

### Stablecoin account details object

<CodeGroup>
  ```json Ethereum theme={null}
  {
    "id": "acd_01HXYZ9012MNOP",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "chain": "eth",
    "account_number": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "supported_assets": ["USDC", "USDT"],
    "issuer": {
      "name": "Ethereum Mainnet",
      "code": "eth"
    },
    "status": "pending",
    "created": 1735725600000,
    "updated": 1735725600000
  }
  ```

  ```json Base theme={null}
  {
    "id": "acd_01HXYZ9012MNOP",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "chain": "base",
    "account_number": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
    "supported_assets": ["USDC", "USDT"],
    "issuer": {
      "name": "Base",
      "code": "base"
    },
    "status": "pending",
    "created": 1735725600000,
    "updated": 1735725600000
  }
  ```

  ```json Polygon theme={null}
  {
    "id": "acd_01HXYZ9012MNOP",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "chain": "matic",
    "account_number": "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063",
    "supported_assets": ["USDC", "USDT"],
    "issuer": {
      "name": "Polygon",
      "code": "matic"
    },
    "status": "pending",
    "created": 1735725600000,
    "updated": 1735725600000
  }
  ```

  ```json Solana theme={null}
  {
    "id": "acd_01HXYZ9012MNOP",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "chain": "sol",
    "account_number": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "supported_assets": ["USDC", "USDT"],
    "issuer": {
      "name": "Solana Mainnet",
      "code": "sol"
    },
    "status": "pending",
    "created": 1735725600000,
    "updated": 1735725600000
  }
  ```
</CodeGroup>

<Note>
  Stablecoin account details are initially created with `status: pending` while the wallet address is being provisioned. Listen for the `account_details.activated` webhook event to know when the address is ready to receive funds.
</Note>

<ResponseField name="chain" type="string">
  The blockchain network the wallet address is on. One of `eth`, `base`, `matic`, `sol`.
</ResponseField>

<ResponseField name="account_number" type="string">
  The provisioned wallet address. EVM-format (`0x...`) for `eth`, `base`, and `matic`; Base58 for `sol`.
</ResponseField>

<ResponseField name="supported_assets" type="array">
  The stablecoins this address can receive. Always `["USDC", "USDT"]`.
</ResponseField>

***

## Expiration

By default, account details are permanent. Pass `terminate_after` to set an expiry date — the details will deactivate automatically after the specified number of days.

```json theme={null}
{
  "account_id": "acc_01HXYZ5678EFGH",
  "terminate_after": 30
}
```

Use cases for expiring account details:

* **Temporary collection accounts** — generate a unique receiving address per transaction that expires after collection
* **Time-limited links** — share banking coordinates that self-deactivate after a campaign or event
* **Short-lived virtual accounts** — provision and expire accounts for one-off payout flows

***

### Webhook: `inflows.completed`

Listen for `inflows.completed` to be notified when funds arrive. This is the authoritative signal that the account has been credited.

```json theme={null}
{
  "event": "inflows.completed",
  "data": {
    "id": "01K6ZXCNMVA04GM3WQRCKQNCMB",
    "amount": 10000,
    "currency": "USD",
    "unique_reference": "01K6ZX7360026KPNA2SQ6NPNZY-1759504425996",
    "counterparty_id": "acct-01K6ZX7360026KPNA2SQ6NPNZY",
    "account_id": "acc_01HXYZ5678EFGH",
    "entity_id": "ent_01HXYZ1234ABCD",
    "status": "successful",
    "status_reason": "Successful.",
    "narration": "Invoice payment received",
    "type": "inflow",
    "applicable_fee": 0,
    "meta": {},
    "created": 1759860119195,
    "updated": 1759860119195
  }
}
```

<ResponseField name="id" type="string">
  Unique identifier for the inflow transaction.
</ResponseField>

<ResponseField name="amount" type="number">
  Amount received in the smallest currency unit. e.g. `10000` = \$100.00 USD.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code of the received funds.
</ResponseField>

<ResponseField name="unique_reference" type="string">
  Idempotency reference for the transaction. Use this to deduplicate webhook deliveries.
</ResponseField>

<ResponseField name="counterparty_id" type="string">
  Identifier for the sender's account.
</ResponseField>

<ResponseField name="account_id" type="string">
  The ID of the Nuvion account that was credited.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The ID of the entity whose account was credited.
</ResponseField>

<ResponseField name="status" type="string">
  Always `successful` for this event.
</ResponseField>

<ResponseField name="narration" type="string">
  Payment reference provided by the sender.
</ResponseField>

<ResponseField name="applicable_fee" type="number">
  Fee applied to the inflow in the smallest currency unit.
</ResponseField>

<ResponseField name="type" type="string">
  Always `inflow`.
</ResponseField>

***

## What's next

<CardGroup cols={3}>
  <Card title="Accept a payment" icon="arrow-down-to-line" href="/guides/accept-a-payment">
    Use account details to receive a bank transfer or stablecoin deposit into an account.
  </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="Account Details API reference" icon="code" href="/api-reference/account-details">
    Full endpoint documentation for creating and managing account details.
  </Card>
</CardGroup>