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.

A ClearBox card is derived from a user’s wallet balance. It lets the user spend their stablecoin anywhere Visa/Mastercard is accepted: when the card is charged, ClearBox burns the equivalent stablecoin from the wallet. Cards are issued through Crossmint’s card extension on top of the wallet you created in Create a wallet.

​
Flow at a glance

1

Request a card for the wallet

The ClearBox backend requests a virtual card derived from the user’s wallet.
2

Receive tokenized card metadata

Crossmint returns the card ID, masked PAN, expiry, and spend controls.
3

Map the card to the user

ClearBox stores the card ID against the user record.

​
1. Request a virtual card

Call Crossmint’s card extension endpoint for the wallet. Set spend controls at issuance to enforce per-transaction or interval limits. 
POST https://www.crossmint.com/api/v1/wallets/{walletId}/extensions/cards
X-API-KEY: <CROSSMINT_SERVER_API_KEY>
Content-Type: application/json

{
  "network": "visa",
  "spendControls": {
    "perTransactionLimit": "100.00",
    "currency": "USD"
  }
}
Crossmint returns tokenized card metadata. Note that the full PAN is never returned in plaintext — you receive a masked PAN and a cardId you use for all later operations. 
{
  "cardId": "crd_9a7b...",
  "maskedPan": "•••• •••• •••• 4242",
  "expiry": "12/29",
  "status": "active",
  "balance": "0.00"
}

​
2. Map the card to the user

Store the cardId against the ClearBox identity so transactions on the card resolve to the right wallet and user. 
PATCH /v1/identities/idn_8f2a...

{
  "card_id": "crd_9a7b...",
  "card_status": "active"
}

​
Funding and spending power

A newly issued card starts at 0.00 spending power. As the wallet is funded, ClearBox updates the card’s available fiat spending power so the card can authorize against it. When the card is later charged, the mirror ledger validates the balance, approves, and ClearBox burns the equivalent stablecoin.
ClearBox keeps the card’s spending power in sync with the wallet’s settled balance. After a deposit settles, the card’s available balance reflects the new funds.

​
Next steps

Apple Pay provisioning

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

Spend controls

Configure limits, merchant rules, and freezes.

​
Reference

The Crossmint card extension path and fields follow Crossmint’s public API. Confirm the current shape against Crossmint’s docs; replace /v1/identities with your ClearBox endpoint.