v5

OpenAPI 3.1.0Proprietary2026-08-011476181.4 MB

Cards

Issue a card

Issue a new card for a cardholder. Every card must be bound to at least one funding source at create time. The cardholder must have KYC status APPROVED before a card can be issued; otherwise the request is rejected with CARDHOLDER_KYC_NOT_APPROVED.

If any funding source is an Embedded Wallet internal account, the cardholder must authorize Grid to sign Spark token transactions for that card funding source by completing the delegated-key creation flow with POST /auth/delegated-keys. Until an active delegated key exists for that funding source, Authorization Decisioning cannot use it to fund card transactions.

New cards start in state: "PROCESSING" while the card issuer provisions the card. The card.state_change webhook fires on each state transition, including the transition to ACTIVE (or to CLOSED with stateReason: "ISSUER_REJECTED" if provisioning fails).

post/cards

Request body

cardholderIdstring required

The id of the Customer to issue the card to. The customer must have KYC status APPROVED; otherwise the request is rejected with CARDHOLDER_KYC_NOT_APPROVED.

platformCardIdstring

Optional platform-specific card identifier. System-generated when omitted, mirroring platformCustomerId semantics.

form'VIRTUAL' required

Physical form factor of the card. Only VIRTUAL is supported in v1; PHYSICAL will be added in a later release.

fundingSourcesstring[] required

Internal account ids to bind as funding sources, in priority order. The first entry is tried first by Authorization Decisioning. Every card must be bound to at least one source, and every source must belong to the cardholder and be denominated in a card-eligible currency (USDB in v1); otherwise the request is rejected with FUNDING_SOURCE_INELIGIBLE.

Example request

{
  "cardholderId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCardId": "card-emp-aary-001",
  "fundingSources": [
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
  ]
}

Response

Card created successfully. Newly-created cards start in PROCESSING while the issuer provisions them. Cards funded by an Embedded Wallet internal account also require an active delegated key for that funding source before Authorization Decisioning can use it.

idstring required

System-generated unique card identifier

cardholderIdstring required

The id of the Customer who holds this card.

platformCardIdstring

Platform-specific card identifier. Optional on create — system-generated if omitted, mirroring platformCustomerId semantics.

state'PENDING_KYC' | 'PROCESSING' | 'ACTIVE' | 'FROZEN' | 'CLOSED' required

Lifecycle state of a card.

State	Description
PENDING_KYC	The cardholder has not yet completed KYC. Cards in this state cannot transact.
PROCESSING	The card has been requested and is being provisioned with the issuer.
ACTIVE	The card is live and can authorize transactions.
FROZEN	The card is temporarily disabled by the platform. New authorizations are declined with CARD_PAUSED. Existing settlements and refunds continue to reconcile.
CLOSED	The card is permanently closed. Terminal, irreversible state.

stateReason'ISSUER_REJECTED' | 'CLOSED_BY_PLATFORM' | 'CLOSED_BY_GRID'

Reason a card reached a terminal or non-active state. Present on CLOSED cards, and on cards that fail provisioning before reaching ACTIVE.

Reason	Description
ISSUER_REJECTED	The card issuer rejected provisioning during PROCESSING.
CLOSED_BY_PLATFORM	The card was closed via PATCH /cards/{id} (state: CLOSED) by the platform.
CLOSED_BY_GRID	The card was closed by Grid (e.g. compliance or risk action).

brand'VISA' | 'MASTERCARD'

Card network brand. Read-only — determined by Grid when the card is provisioned with the issuer.

form'VIRTUAL' required

Physical form factor of the card. Only VIRTUAL is supported in v1; PHYSICAL will be added in a later release.

last4string

Last four digits of the card PAN.

expMonthinteger

Card expiration month (1–12).

expYearinteger

Card expiration year (four digits).

fundingSourcesstring[] required

Internal account ids bound to this card as funding sources, in priority order — the first entry is tried first by Authorization Decisioning. Every card has at least one funding source.

currencystring

Currency the card transacts in (ISO 4217 for fiat, tickers for crypto). Derived from the funding sources at issue time — all funding sources bound to a card must be denominated in the same card-eligible currency.

processorRefstring

Opaque processor-side reference for the card (e.g. the Lithic card token). Useful for cross-referencing in the processor's dashboards; not used for any Grid request routing.

issuerRefstring

Opaque identifier for the card on the issuer of record (e.g. the Lead Bank account/card identifier). Useful for cross-referencing in issuer dashboards; not used for any Grid request routing.

createdAtstring date-time required

Creation timestamp

updatedAtstring date-time required

Last update timestamp

Example response

{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "cardholderId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCardId": "card-emp-aary-001",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "fundingSources": [
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000003"
  ],
  "currency": "USD",
  "processorRef": "card_b81c2a4f",
  "issuerRef": "lead_card_7a1b9c3d",
  "createdAt": "2026-05-08T14:10:00Z",
  "updatedAt": "2026-05-08T14:11:00Z"
}