Issuing Cards

A card is created with a single POST /cards request and progresses through a fixed lifecycle. This page covers the request shape, what happens after issuance, and the errors you should handle.

Request shape

curl -X POST "$GRID_BASE_URL/cards" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "form": "VIRTUAL",
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "maxSpendPerTransaction": 5000,
    "maxSpendPerDay": 25000,
    "maxTransactionsPerDay": 20
  }'

Field	Required	Notes
`customerId`	Yes	The `Customer` that owns the card. Must be `kycStatus: APPROVED`.
`platformCardId`	No	Ignored if supplied. The value on the returned `Card` is generated by the server.
`form`	Yes	`VIRTUAL` in v1. `PHYSICAL` will be added later.
`fundingSource`	Yes	The `InternalAccount` that funds the card. Must belong to the customer and be denominated in a card-eligible currency.
`maxSpendPerTransaction`	No	The largest amount the card can authorize on a single transaction, in the smallest unit of the card’s currency (cents for USD). An authorization for exactly the limit is allowed; a later clearing can still settle above it (e.g. a restaurant tip). Omit for no limit. Available only on card programs where Grid makes the authorization decision.
`maxSpendPerDay`	No	Cumulative new spend allowed per UTC calendar day, in the smallest unit of the card’s currency. Refunds, reversals, and expiries do not restore capacity that day.
`maxTransactionsPerDay`	No	Number of transactions the card may authorize per UTC calendar day. Each approved authorization counts once; reversals and expiries do not restore capacity that day.

The card program fixes the card’s currency at issuance and returns it on the Card resource. USDB-funded cards have currency: "USD", with funding converted at 1 USDB = 1 USD. Spending limits use the smallest unit of the card’s currency: for a USDB-funded card, 50000 means $500.00 in USD cents. Changing the funding source does not change the card’s currency or spending-limit units.

The lifecycle

PROCESSING ──► ACTIVE ◄──► FROZEN
                 │
                 └──► CLOSED

State	When you see it
`PROCESSING`	Returned synchronously from `POST /cards`. The card cannot transact yet.
`ACTIVE`	Issuer provisioned the card. Reached via `CARD.STATUS_CHANGE` webhook.
`FROZEN`	You called `PATCH /cards/{id}` with `status: "FROZEN"`.
`CLOSED`	You called `PATCH /cards/{id}` with `status: "CLOSED"`. Terminal.

PENDING_KYC is also a valid status but you should not see it in v1 — issuance is gated on KYC up front.

After issuance

POST /cards returns immediately with status: "PROCESSING". The issuer provisions the card asynchronously; on success a CARD.STATUS_CHANGE webhook fires with the activated Card resource including the populated last4, expMonth, and expYear.

Revealing the PAN

To show the cardholder their full PAN, CVV, and expiry, request a reveal right before rendering:

curl -X POST "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010/reveal" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

{
  "panEmbedUrl": "https://embed.lithic.com/iframe/...?t=...",
  "expiresAt": "2026-05-08T14:16:00Z"
}

panEmbedUrl is a signed URL for the card processor’s iframe that renders the full credentials directly to the cardholder. The full PAN and CVV never cross your servers or Grid’s.

For cards in programs where Grid makes authorization decisions, POST /cards/{id}/reveal is the only way to obtain a reveal URL; cards in programs where the card issuer makes authorization decisions use the card issuer’s challenge-based hosted reveal flow instead. The Card resource never carries one (not in responses, not in webhook payloads). The URL expires at expiresAt (within minutes), so request a fresh reveal each time the cardholder asks for their details, immediately before rendering the iframe. Never store, cache, or log the URL. Every reveal is audit-logged.

Errors to handle

Status	Code	What it means
400	`CARDHOLDER_KYC_NOT_APPROVED`	Cardholder is not `kycStatus: APPROVED`. Drive KYC to completion before retrying.
400	`INVALID_INPUT`	The supplied internal account doesn’t belong to the cardholder or isn’t denominated in a card-eligible currency, or another field failed validation.
409	`CONFLICT`	The card belongs to a program where the card issuer makes authorization decisions. Use the card issuer’s challenge-based hosted reveal flow instead; retrying this endpoint will not help.

Changing the funding source later

The bound funding source can be replaced after issuance via PATCH /cards/{id} with a new fundingSource. See Funding sources for the rules and request example.

Listing cards

curl -X GET "$GRID_BASE_URL/cards?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001&limit=20" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Filter by customerId, platformCardId, or status. The response is paginated using the standard cursor shape used by other Grid list endpoints.

Overview

Onboarding

Card management

Transactions

Card design

Platform tools

Request shape

The lifecycle

After issuance

Revealing the PAN

Errors to handle

Changing the funding source later

Listing cards

​Request shape

​The lifecycle

​After issuance

​Revealing the PAN

​Errors to handle

​Changing the funding source later

​Listing cards

Request shape

The lifecycle

After issuance

Revealing the PAN

Errors to handle

Changing the funding source later

Listing cards