Cards
Update a card
Changed onUpdate a card's status, funding source, merchant categories, risk ceiling, or threeDSecurePassword. At least one field must be supplied. Manage velocity limits through /card-velocity-limits.
- status transitions include ACTIVE ⇄ FROZEN, PENDING_AUTH → ACTIVE | FROZEN, and ACTIVE | PENDING_AUTH | FROZEN → CLOSED. CLOSED is terminal and irreversible. Activating a card whose USDB funding source lacks a usable delegated key returns 409 INVALID_STATE_TRANSITION. PENDING_AUTH is managed by Grid and cannot be requested. Completing delegation does not unfreeze or reopen a card. Requesting status: ACTIVE returns 409 INVALID_STATE_TRANSITION while the customer is not ACTIVE, for a card Grid froze for review, and for a card frozen with substatus COMPROMISED. Contact Grid support to have such a card reviewed, or close a compromised card and issue a new one.
- fundingSource, when supplied, replaces the card's bound internal account. It must belong to the customer and use a currency supported by the card program, including USDB for USD cards. An active card becomes PENDING_AUTH when switched to USDB without an active delegated key. Switching back to USD restores readiness. fundingSource cannot be supplied alongside status: CLOSED. On card programs where the card issuer makes authorization decisions, fundingSource cannot be combined with any status change, so send the changes as separate requests. On card programs where Grid makes the authorization decision, the combination remains valid for status changes other than CLOSED. This endpoint is authenticated by the platform credential alone and returns 200 directly. It deliberately does not use Grid's 202 → signed-retry pattern: that pattern signs with the session key of a credential on the owning internal account, so it models actions taken by the end user on their own credentials or funds. Freezing or closing a card is routinely an action taken about a user and without them present - fraud response, offboarding, an ops-driven freeze - and requiring the cardholder's signature would make exactly those cases impossible. Operations that expose sensitive card data (POST /cards/{id}/reveal, 3DS password retrieval) are SCA-railed instead, because there the cardholder is the party being served.
Effects:
- status: FROZEN: Authorization Decisioning declines new auths with cardDeclinedReason: CARD_NOT_ACTIVE. Existing pulls and in-flight reconciliation continue — freezing does not pause the lifecycle of authorizations that already passed.
- status: ACTIVE: normal authorization behavior resumes.
- status: CLOSED: terminal close. The card transitions to status: "CLOSED" with statusReason: "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. The funding source is detached. Refunds already in flight still complete because Lightspark holds the card-reserve keys.
- fundingSource change: returns the updated card with the new binding and fires no webhook.
The card.status_change webhook fires on every successful status transition.
patch/cards/{id}
Request
- Base URLhttps://api.lightspark.com/grid/2025-10-13
- URLhttps://api.lightspark.com/grid/2025-10-13/cards/{id}
- AuthHTTP basic
Request body
Example request
{
"status": "FROZEN",
"substatus": "SUSPICIOUS_ACTIVITY",
"reason": "Cardholder reported the card stolen.",
"fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
"maxNetworkRiskScore": 700,
"threeDSecurePassword": "AbCd1234EfGh5678",
"allowedMccs": [
"5411"
],
"blockedMccs": [
"7995"
],
"defaultMccBlocksLifted": true
}Response
Card updated. Returns the updated card.
Example response
{
"id": "Card:019542f5-b3e7-1d02-0000-000000000010",
"customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
"platformCardId": "card-emp-001",
"pinStatus": "OK",
"pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
"last4": "4242",
"expMonth": 12,
"expYear": 2029,
"fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
"cardCapabilities": {
"supportsVelocityLimits": true,
"supportsPanReveal": true,
"supportsDigitalWalletTokenization": true
},
"maxNetworkRiskScore": 700,
"allowedMccs": [
"5411"
],
"blockedMccs": [
"7995"
],
"agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
"currency": "USD",
"processorRef": "card_b81c2a4f",
"issuerRef": "lead_card_7a1b9c3d",
"createdAt": "2026-05-08T14:10:00Z",
"updatedAt": "2026-05-08T14:11:00Z"
}Changes
- info
added the optional property
/to the response with the status - info
added the optional property
/to the response with the status
- info
- breaking
removed the required property
/from the response with the status - breaking
removed the required property
/from the response with the status - breaking
removed the required property
/from the response with the status - breaking
removed the required property
from the response with the status - breaking
removed the required property
from the response with the status - breaking
removed the required property
from the response with the status - warning
removed the request property
- warning
removed the request property
- warning
removed the request property
- info
added the required property
/to the response with the status
- breaking