Update a card

Update a card’s state and / or its bound fundingSources. At least one of the two fields must be supplied.

• state transitions are limited to ACTIVE ⇄ FROZEN and ACTIVE | FROZEN → CLOSED. CLOSED is terminal and irreversible. Any other transition returns 409 INVALID_STATE_TRANSITION.
• fundingSources, when supplied, fully replaces the card’s bound funding sources. Array order determines the priority Authorization Decisioning tries them in. Each id must belong to the cardholder and be denominated in the card’s currency; the list must contain at least one source. fundingSources cannot be supplied alongside state: CLOSED.

Because both updates are sensitive state changes, this endpoint uses Grid’s 202 → signed-retry pattern (same shape as DELETE /auth/credentials/{id} and POST /internal-accounts/{id}/export):

1. Call PATCH /cards/{id} with the target fields and no signing headers. The response is 202 with a payloadToSign, requestId, and expiresAt.

2. Sign the payloadToSign with the session private key of a verified authentication credential on the card’s owning internal account and retry with the signature as the Grid-Wallet-Signature header and the requestId echoed back as the Request-Id header. The signed retry returns 200 with the updated Card.

Effects:

• state: FROZEN: Authorization Decisioning declines new auths with CARD_PAUSED. Existing pulls and in-flight reconciliation continue — freezing does not pause the lifecycle of authorizations that already passed.
• state: ACTIVE: normal authorization behavior resumes.
• state: CLOSED: terminal close. The card transitions to state: "CLOSED" with stateReason: "CLOSED_BY_PLATFORM" and stays in the system for audit and reconciliation. All pending auths reconcile to a terminal state via the existing reconcile primitive. Inbound clearings received after close follow the standard force-post / late-presentment path — Lightspark absorbs the loss if a post-hoc pull on the now-unbound source fails. Funding-source bindings are detached. Refunds already in flight still complete because Lightspark holds the card-reserve keys.
• fundingSources change: emits card.funding_source_change reflecting the new ordered binding.

The card.state_change webhook fires on every successful state transition; the card.funding_source_change webhook fires whenever fundingSources is updated.

PATCH /cards/{id}

cURL

cURL

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/cards/{id} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "state": "FROZEN"
}
'

200

{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "cardholderId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "fundingSources": [
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000003"
  ],
  "createdAt": "2026-05-08T14:10:00Z",
  "updatedAt": "2026-05-08T14:11:00Z",
  "platformCardId": "card-emp-aary-001",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "panEmbedUrl": "https://embed.lithic.com/iframe/...?t=...",
  "currency": "USD",
  "issuerRef": "lithic_card_4f8d3a2b1c"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Headers

Grid-Wallet-Signature · string

Signature over the payloadToSign returned in a prior 202 response, produced with the session private key of a verified authentication credential on the card's owning internal account and base64-encoded. Required on the signed retry; ignored on the initial call.

Request-Id · string

The requestId returned in a prior 202 response, echoed back on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry; must be paired with Grid-Wallet-Signature.

Path Parameters

id · string · required

System-generated unique card identifier

Body

application/json

Update request for PATCH /cards/{id}. At least one of state or fundingSources must be supplied. state transitions are limited to ACTIVE ⇄ FROZEN and ACTIVE | FROZEN → CLOSED; any other transition returns 409 INVALID_STATE_TRANSITION. CLOSED is terminal and irreversible and cannot be combined with fundingSources. fundingSources, when supplied, fully replaces the card's bound funding sources — the array order determines the priority Authorization Decisioning tries them in.

state · enum<string>

Target state for the card. Permitted transitions are ACTIVE ⇄ FROZEN and ACTIVE | FROZEN → CLOSED. CLOSED is terminal and irreversible; once closed, the card stays in the system for audit and reconciliation but cannot transact again.

Available options: ACTIVE, FROZEN, CLOSED

Example:

"FROZEN"

fundingSources · string[]

New ordered list of internal account ids to bind as funding sources. Fully replaces the previous binding. Each id must belong to the cardholder and be denominated in the card's currency. The list must contain at least one source — to stop a card from spending without removing all sources, transition it to FROZEN instead. Cannot be supplied alongside state: CLOSED.

Minimum array length: 1

Example:

[
  "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "InternalAccount:019542f5-b3e7-1d02-0000-000000000003"
]

Response

200

application/json

Signed retry accepted. Returns the updated card.

id · string · required · read-only

System-generated unique card identifier

Example:

"Card:019542f5-b3e7-1d02-0000-000000000010"

cardholderId · string · required

The id of the Customer who holds this card.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

state · enum<string> · required

Lifecycle state of a card.

State	Description
PENDING_KYC	The cardholder has not yet completed KYC. Cards in this state cannot transact.
PENDING_ISSUE	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.

Available options: PENDING_KYC, PENDING_ISSUE, ACTIVE, FROZEN, CLOSED

form · enum<string> · required

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

Available options: VIRTUAL

fundingSources · string[] · 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.

Example:

[
  "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "InternalAccount:019542f5-b3e7-1d02-0000-000000000003"
]

createdAt · string<date-time> · required · read-only

Creation timestamp

Example:

"2026-05-08T14:10:00Z"

updatedAt · string<date-time> · required · read-only

Last update timestamp

Example:

"2026-05-08T14:11:00Z"

platformCardId · string

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

Example:

"card-emp-aary-001"

stateReason · enum<string> | null

Reason associated with the current state. Populated when the card is CLOSED or when provisioning was rejected; otherwise null.

Available options: ISSUER_REJECTED, CLOSED_BY_PLATFORM, CLOSED_BY_GRID

brand · enum<string>

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

Available options: VISA, MASTERCARD

last4 · string

Last four digits of the card PAN.

Example:

"4242"

expMonth · integer

Card expiration month (1–12).

Required range: 1 <= x <= 12

Example:

12

expYear · integer

Card expiration year (four digits).

Example:

2029

panEmbedUrl · string<uri>

URL of the card issuer's iframe that securely displays the PAN, CVV, and expiry to the cardholder. The full PAN and CVV never cross Grid's servers — render this URL in an iframe in your client to reveal card details.

Example:

"https://embed.lithic.com/iframe/...?t=..."

currency · string · read-only

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.

Example:

"USD"

issuerRef · string · read-only

Opaque identifier for the card on the underlying issuer. Useful for cross-referencing in issuer dashboards; not used for any Grid request routing.

Example:

"lithic_card_4f8d3a2b1c"