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
The card’s
currency is derived from the funding sources at issue time
and surfaces on the returned Card resource — all bound sources share
one currency.
The lifecycle
PENDING_KYC is also a valid state but you should not see it in v1 —
issuance is gated on KYC up front.
After issuance
POST /cards returns immediately with state: "PROCESSING". The
issuer provisions the card asynchronously; on success a
CARD.STATE_CHANGE webhook fires with the activated Card resource
including the populated last4, expMonth, and expYear.
If the issuer rejects provisioning, the same webhook fires with
state: "CLOSED" and stateReason: "ISSUER_REJECTED". That card is
terminal — issue a new one with a fresh platformCardId to retry.
Revealing the PAN
To show the cardholder their full PAN, CVV, and expiry, request a reveal right before rendering: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.
POST /cards/{id}/reveal is the only way to obtain a reveal URL —
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
Changing funding sources later
The bound funding sources can be replaced after issuance viaPATCH /cards/{id} with a new fundingSources array. See
Funding sources for the rules
and the signed-retry flow.
Listing cards
cardholderId, platformCardId, or state. The response is
paginated using the standard cursor shape used by other Grid list
endpoints.