Cards API

Issue virtual and physical debit cards powered by your USDC wallet balance. Manage spending limits, and handle real-time authorizations via webhooks.

Issue a Card

Issue virtual or physical cards for your business users. Virtual cards are available instantly.

POST/v1/cards

Parameter	Type	Description
`type`required	`string`	"virtual" or "physical".
`cardholder_name`required	`string`	Name to print on the card.
`business_user_id`required	`string`	ID of the business user this card is assigned to.
`card_program_id`	`string`	Card program to issue under (uses default if omitted).
`currency`	`string`	Card currency (default: "USD").
`spending_limits`	`object`	Spending limits for the card.
`spending_limits.daily`	`number`	Daily spending limit (positive integer).
`spending_limits.monthly`	`number`	Monthly spending limit (positive integer).
`spending_limits.per_transaction`	`number`	Per-transaction limit (positive integer).

Scope required

This endpoint requires the cards:write scope and a verified business.

Example request

curl -X POST https://api.chain.com/v1/cards \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "virtual",
    "cardholder_name": "Jane Doe",
    "business_user_id": "usr_abc123",
    "currency": "USD",
    "spending_limits": {
      "daily": 5000,
      "monthly": 25000,
      "per_transaction": 2500
    }
  }'

Response

{
  "id": "card_def456",
  "type": "virtual",
  "last_four": "4242",
  "masked_pan": "****4242",
  "cardholder_name": "Jane Doe",
  "currency": "USD",
  "status": "active",
  "cvv": "123",
  "expiration_month": 12,
  "expiration_year": 2028,
  "created_at": "2026-01-15T10:05:00Z"
}

Sensitive data

Full card details (CVV, expiration) are only returned in the creation response for virtual cards. Store them securely — they cannot be retrieved again via the API.

List Cards

Retrieve all cards for your business with optional filtering.

GET/v1/cards

Parameter	Type	Description
`limit`	`number`	Results per page (default 20, max 100).
`starting_after`	`string`	Cursor for pagination — card ID to start after.
`status`	`string`	Filter by status: "active", "frozen", "cancelled", "pending".

Response

{
  "data": [
    {
      "id": "card_def456",
      "type": "virtual",
      "last_four": "4242",
      "masked_pan": "****4242",
      "cardholder_name": "Jane Doe",
      "currency": "USD",
      "status": "active",
      "created_at": "2026-01-15T10:05:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Card Management

Cards can be frozen, unfrozen, and cancelled from the Chain Dashboard. Card status changes trigger webhook events for real-time monitoring.

Action	Description
Freeze	Temporarily disable the card. No transactions allowed while frozen.
Unfreeze	Re-enable a frozen card for transactions.
Cancel	Permanently cancel the card. This cannot be undone.

Real-Time Authorization

Receive real-time webhook events when a cardholder makes a purchase. Respond within 2 seconds to approve or decline the transaction.

Authorization webhook payload

{
  "type": "card.authorization.request",
  "data": {
    "card_id": "card_def456",
    "amount": 42.50,
    "currency": "USD",
    "merchant": {
      "name": "Coffee Shop",
      "mcc": "5814",
      "city": "San Francisco"
    }
  },
  "respond_url": "https://api.chain.com/v1/authorizations/auth_789/respond"
}

Approve or decline

curl -X POST https://api.chain.com/v1/authorizations/auth_789/respond \
  -H "Authorization: Bearer sk_live_..." \
  -d '{"approved": true}'

Card Statuses

Status	Description
`active`	Card is active and can process transactions.
`frozen`	Card is temporarily frozen. No transactions allowed.
`cancelled`	Card is permanently cancelled.
`pending`	Physical card is being manufactured/shipped.