Freezing & Closing Cards

Freeze, unfreeze, and close cards via the signed-retry pattern

Freeze, close, and other card updates use a single authenticated PATCH /cards/{id} request and return the updated card with 200 OK.

PATCH /cards/{id} covers status, funding source, and other card settings. See Funding sources for the funding-source-only flow and Velocity limits for amount and count caps.

​

Valid status transitions

From	To	Endpoint
ACTIVE	FROZEN	PATCH /cards/{id} body { "status": "FROZEN" }
FROZEN	ACTIVE	PATCH /cards/{id} body { "status": "ACTIVE" }
ACTIVE or FROZEN	CLOSED	PATCH /cards/{id} body { "status": "CLOSED" }

Any other transition returns 409 INVALID_STATE_TRANSITION. In particular, you cannot un-freeze a CLOSED card — close is terminal.

{ "status": "ACTIVE" } also returns 409 INVALID_STATE_TRANSITION when:

• the customer is not ACTIVE;
• Grid froze the card for review; or
• the card was frozen with substatus COMPROMISED, including by you.

Contact Grid support to have a card reviewed. A compromised card cannot be unfrozen: close it and issue a new one. Once a suspended customer is ACTIVE again, you can unfreeze cards that were frozen only because of the suspension.

You can also combine a status change with a funding source replacement in one PATCH — just include both fields in the body.

curl -X PATCH "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "FROZEN" }'

The response is 200 OK with the updated Card and a CARD.STATUS_CHANGE webhook.

​

What freeze does

Setting a card to FROZEN:

• Causes Authorization Decisioning to decline new auths with cardDeclinedReason: CARD_NOT_ACTIVE.
• Does not pause the lifecycle of authorizations that already passed. Pulls, clearings, and refunds against existing transactions continue to reconcile normally.
• Emits CARD.STATUS_CHANGE with status: "FROZEN".

Unfreeze (status: "ACTIVE") reverses this — new auths flow normally again.

​

What close does

Closing a card is done with the same PATCH /cards/{id} endpoint by setting status: "CLOSED". The operation is permanent:

• Card status transitions to CLOSED, statusReason: "CLOSED_BY_PLATFORM".
• All pending authorizations reconcile to a terminal state via the existing reconcile primitive.
• Funding-source bindings are detached. Refunds already in flight continue to complete because Lightspark holds the card-reserve keys.
• 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.
• CARD.STATUS_CHANGE fires with status: "CLOSED".

curl -X PATCH "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "CLOSED" }'

fundingSource cannot be supplied alongside status: CLOSED. 409 CARD_ALREADY_CLOSED is returned if the card is already in the terminal CLOSED state.

​

Managing velocity limits

Use Velocity limits to configure per-authorization, daily, rolling, and other calendar-window amount and count caps. PATCH /cards/{id} changes the card’s status and other card settings; velocity limits are managed through /card-velocity-limits.

​

Sandbox behavior

In Sandbox the status changes are instant — no issuer round-trip is simulated. The request and response shape is the same as production.