Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clear-box.io/llms.txt

Use this file to discover all available pages before exploring further.

This quickstart takes you from zero to a settled test transaction in the sandbox. It mirrors the production flow but uses test credentials and simulated funds.
You’ll need a ClearBox sandbox API key. Generate one from the Dashboard under Settings → API Keys. See Authentication for details.

​
Prerequisites

  • A ClearBox sandbox account and API key
  • curl or an HTTP client
  • The sandbox base URL: https://sandbox.api.clearbox.example.com

​
1. Create a verified identity

In production, identity is verified through ClearCheck (Persona). In the sandbox you can create a pre-verified test identity directly. 
curl -X POST https://sandbox.api.clearbox.example.com/v1/identities \
  -H "Authorization: Bearer $CLEARBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com",
    "date_of_birth": "1990-12-10",
    "kyc_status": "approved"
  }'
The response includes an identity_id you’ll use to provision a wallet. 
{
  "identity_id": "idn_test_8f2a...",
  "kyc_status": "approved",
  "created_at": "2026-05-28T16:00:00Z"
}

​
2. Provision a wallet

Create an embedded, non-custodial wallet for the verified identity. 
curl -X POST https://sandbox.api.clearbox.example.com/v1/wallets \
  -H "Authorization: Bearer $CLEARBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "identity_id": "idn_test_8f2a..." }'

{
  "wallet_id": "wlt_test_5c1d...",
  "wallet_address": "0xA1b2...C3d4",
  "chain": "polygon",
  "balance": { "currency": "USDC", "amount": "0.00" }
}

​
3. Fund the wallet

In the sandbox, simulate a deposit instead of running a real ACH transfer. 
curl -X POST https://sandbox.api.clearbox.example.com/v1/wallets/wlt_test_5c1d.../simulate-deposit \
  -H "Authorization: Bearer $CLEARBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "100.00", "currency": "USDC" }'

​
4. Issue a card

Derive a spendable virtual card from the wallet balance. 
curl -X POST https://sandbox.api.clearbox.example.com/v1/cards \
  -H "Authorization: Bearer $CLEARBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "wlt_test_5c1d...",
    "spend_limit": { "amount": "100.00", "interval": "transaction" }
  }'

​
5. Simulate a transaction

Simulate a tap at a terminal and watch the mirror ledger authorize it. 
curl -X POST https://sandbox.api.clearbox.example.com/v1/transactions/simulate \
  -H "Authorization: Bearer $CLEARBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "crd_test_9a7b...",
    "amount": "15.00",
    "merchant": "Sandbox Coffee"
  }'
A successful response shows the authorization and the resulting balance. 
{
  "transaction_id": "txn_test_2f9e...",
  "status": "approved",
  "authorized_in_ms": 198,
  "wallet_balance_after": { "currency": "USDC", "amount": "85.00" }
}
You’ve run a full ClearBox flow: a verified identity, a funded wallet, an issued card, and a settled transaction.

​
Where to go next

Link a real bank

Replace the simulated deposit with a live Quiltt connection.

Apple Pay provisioning

Push the issued card into Apple Wallet for tap-to-pay.