Customers
A Customer represents a person or business using your platform. Every resource in Ledger — wallets, cards, virtual accounts, payout accounts — belongs to a Customer. Before a customer can hold funds or make payments, they need to pass identity verification (KYC/KYB). Ledger handles this for you.| Field | Values |
|---|---|
type | individual, business |
status | pending, active, suspended, rejected |
kycStatus | not_started, under_review, incomplete, approved, rejected |
capabilities | cards, wallets, virtualAccounts, transfers |
Wallets
A Wallet is a custodial crypto wallet Ledger manages on behalf of a customer. Wallets hold stablecoin balances and are the foundation for most money movement.| Field | Values |
|---|---|
chain | solana, ethereum, base, arbitrum, tron |
status | active, frozen, closed |
walletType | custodial, self_custodial |
- Receive deposits via crypto deposit addresses or virtual accounts
- Send transfers to other wallets or external addresses
- Fund card spend
- Hold stablecoin balances
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) |
destinationCurrency | Stablecoin funds convert to (usdc, usdb) |
destinationPaymentRail | Chain funds settle on (solana) |
depositInstructions | Bank details to share with senders |
Payout Accounts
A Payout Account 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
Cards
A Card is a virtual or physical payment card issued to a customer, funded by their wallet balance. Cards can be used anywhere Visa is accepted.| Field | Values |
|---|---|
type | virtual, physical |
status | active, locked, canceled |
spendingLimit.frequency | per24HourPeriod, per7DayPeriod, per30DayPeriod, allTime |
Transactions
A Transaction records any value movement in Ledger. Every deposit, card purchase, transfer, and withdrawal creates a transaction.| Type | Description |
|---|---|
card_spend | Purchase made with a card |
transfer | Fiat-to-crypto, crypto-to-fiat, or cross-chain transfer |
deposit | Fiat deposited via a virtual account |
withdrawal | Funds withdrawn to a payout account |
wallet_deposit | Crypto received at a deposit address |
Transfers
A Transfer is a directed movement of value that you initiate. Unlike transactions (which are records), a transfer is an action. Examples:- USDC on Solana to USDC on Ethereum (cross-chain)
- USDC on Solana to USD via ACH (off-ramp)
- USD via wire to USDC on Solana (on-ramp)
Webhooks
Webhooks let you receive real-time notifications when events happen in Ledger. Register a URL and Ledger pushes events to you. Event types include:customer.created, customer.updated, wallet.created, virtual_account.created, card.created, card.updated, transaction.created, transaction.updated, dispute.created, dispute.updated, webhook.test
IDs
Every resource has a prefixed ID:| Prefix | Resource |
|---|---|
cus_ | Customer |
wal_ | Wallet |
cda_ | Crypto Deposit Address |
va_ | Virtual Account |
pa_ | Payout Account |
card_ | Card |
txn_ | Transaction |
dis_ | Dispute |
rpt_ | Report |
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 cards, real bank transfers. |