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

# Concepts

> The core objects and mental model for building with Ledger.

## Customers

A Customer represents a person or business using your platform. Every resource in Ledger — crypto wallets, virtual accounts, counterparties — belongs to a Customer.

Customers are active immediately on creation. To unlock capabilities like crypto wallets and transfers, customers need to pass identity verification (KYC/KYB). Ledger handles this for you.

| Field          | Values                                                              |
| -------------- | ------------------------------------------------------------------- |
| `type`         | `individual`, `business`                                            |
| `status`       | `active`, `suspended`, `rejected`                                   |
| `kycStatus`    | `not_started`, `under_review`, `incomplete`, `approved`, `rejected` |
| `capabilities` | `cryptoWallets`, `virtualAccounts`, `transfers`                     |

Verification links:

* `kycLink`: hosted identity verification URL
* `tosLink`: hosted terms acceptance URL

## Crypto Wallets

A Crypto Wallet is a custodial onchain wallet Ledger manages on behalf of a customer. Crypto wallets hold stablecoin balances and are the foundation for most money movement.

What you can do with a crypto wallet:

* Receive deposits via crypto deposit addresses
* Send onchain or fiat transfers
* Check balance via the balance endpoint
* Hold stablecoin balances (USDC, USDT, PYUSD, EURC)

## Virtual Accounts

A Virtual Account provides fiat deposit instructions (routing/account numbers, IBAN, CLABE, etc.) that route incoming fiat into a linked wallet as stablecoins.

| Field                 | Description                                         |
| --------------------- | --------------------------------------------------- |
| `sourceCurrency`      | Fiat currency accepted (`usd`, `eur`, `mxn`, `gbp`) |
| `depositInstructions` | Bank details to share with senders                  |

## Counterparties

A Counterparty is a customer-owned external account that can receive funds — bank accounts, mobile money wallets, or international wire destinations.

Supported types: `us_bank`, `iban`, `clabe`, `pix`, `gb_bank`, `mobile_money`, `ghipss`, `nip`, `swift`

Bank-backed types (us\_bank, iban, clabe, pix, gb\_bank) require customer KYC approval. Direct types (mobile\_money, ghipss, nip, swift) can be created without KYC.

## Transactions

A Transaction records any value movement in Ledger. Every deposit and transfer creates a transaction.

| Type             | Description                             |
| ---------------- | --------------------------------------- |
| `transfer`       | Onchain transfer to an external address |
| `wallet_deposit` | Crypto received at a deposit address    |

Transaction fields vary by type:

**Crypto transfers** include: `destinationAddress`, `destinationTxHash`, `gasFee`, `finalAmount`, `exchangeFee`

**Fiat transfers** include: `payoutAccountId`, `finalAmount`, `exchangeFee`

Transactions are read-only — they are created automatically when money moves through the system.

## Transfers

A Transfer is a directed movement of value that you initiate via `POST /v1/transfers`. It creates a transaction automatically.

The source is always the customer's crypto wallet. You specify the destination:

* Crypto address on any supported chain (onchain transfer)
* Payout account (`pa_...`) via a fiat rail like ACH, SEPA, or Faster Payments (requires customer KYC)

## Webhooks

Webhooks let you receive real-time notifications when events happen in Ledger. Register a URL and Ledger pushes events to you.

Event types:

* `customer.created`, `customer.updated`
* `wallet.created`, `wallet.updated`
* `virtual_account.created`, `virtual_account.updated`
* `transaction.created`, `transaction.updated`, `transaction.completed`
* `counterparty.created`
* `webhook.test`

## IDs

Every resource has a prefixed ID:

| Prefix | Resource               |
| ------ | ---------------------- |
| `cus_` | Customer               |
| `wal_` | Crypto Wallet          |
| `cda_` | Crypto Deposit Address |
| `va_`  | Virtual Account        |
| `pa_`  | Counterparty           |
| `txn_` | Transaction            |
| `whk_` | Webhook                |

## Environments

| Environment | API key prefix | Description                                   |
| ----------- | -------------- | --------------------------------------------- |
| Sandbox     | `ld_test_`     | Development and testing. No real money moves. |
| Live        | `ld_live_`     | Production. Real funds, real transfers.       |