Update a card

Update 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}

cURL

freeze

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 '
{
  "status": "FROZEN",
  "substatus": "SUSPICIOUS_ACTIVITY",
  "reason": "Unrecognised charges reported by the cardholder."
}
'

200

{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "status": "PENDING_KYC",
  "form": "VIRTUAL",
  "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "createdAt": "2026-05-08T14:10:00Z",
  "updatedAt": "2026-05-08T14:11:00Z",
  "platformCardId": "card-emp-001",
  "statusReason": "DELEGATION_REQUIRED",
  "brand": "VISA",
  "pinStatus": "OK",
  "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "cardCapabilities": {
    "supportsVelocityLimits": true,
    "supports3dSecurePassword": false,
    "supportsPanReveal": true,
    "supportsDigitalWalletTokenization": true
  },
  "maxNetworkRiskScore": 700,
  "allowedMccs": [
    "5411"
  ],
  "blockedMccs": [
    "7995"
  ],
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "defaultMccBlocksLifted": false,
  "lockedMerchant": {
    "descriptor": "BLUE BOTTLE COFFEE SF",
    "mcc": "5814",
    "city": "San Francisco",
    "state": "CA",
    "country": "US"
  },
  "currency": "USD",
  "processorRef": "card_b81c2a4f",
  "issuerRef": "lead_card_7a1b9c3d"
}

Authorizations

Authorization · string · header · required

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

Path Parameters

id · string · required

System-generated unique card identifier

Body

application/json

Update request for PATCH /cards/{id}. At least one of status, fundingSource, maxNetworkRiskScore, allowedMccs, blockedMccs, defaultMccBlocksLifted, or threeDSecurePassword must be supplied. defaultMccBlocksLifted counts only on a card issued for an agent. Fields that do not count are ignored. Supplying status also requires substatus and reason, so every card state change carries why it happened. status transitions include ACTIVE ⇄ FROZEN, PENDING_AUTH → ACTIVE | FROZEN, and ACTIVE | PENDING_AUTH | FROZEN → CLOSED. Explicit activation requires completed delegated signing authorization; otherwise it returns 409 INVALID_STATE_TRANSITION. Funding-source changes reconcile ACTIVE / PENDING_AUTH automatically. PENDING_AUTH cannot be requested. CLOSED is terminal and irreversible and cannot be combined with fundingSource or maxNetworkRiskScore. Manage velocity limits through /card-velocity-limits.

status · enum<string>

Target status for the card. Permitted transitions are ACTIVE ⇄ FROZEN, PENDING_AUTH → ACTIVE | FROZEN, and ACTIVE | PENDING_AUTH | FROZEN → CLOSED. Activation requires completed delegated signing authorization. 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"

substatus · enum<string>

Why the card is moving, in the card issuer's vocabulary. Required whenever status is supplied, and forwarded to the issuer. Pick OTHER when none of the named values fit and say why in reason.

Available options: LOST, COMPROMISED, DAMAGED, END_USER_REQUEST, ISSUER_REQUEST, NOT_ACTIVE, SUSPICIOUS_ACTIVITY, INTERNAL_REVIEW, EXPIRED, UNDELIVERABLE, OTHER

Example:

"SUSPICIOUS_ACTIVITY"

reason · string

A short sentence naming why the card is moving. Required whenever status is supplied, and recorded against the card so a later reader can tell why it changed.

Minimum string length: 1

Example:

"Cardholder reported the card stolen."

fundingSource · string

Replaces the card's funding source. Must belong to the customer and be denominated in a currency supported by the card's program, including USDB for USD cards. Changing the funding source does not change the card's currency or spending-limit units. Cannot be supplied alongside status: CLOSED. To stop a card from spending, set status: FROZEN instead.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

maxNetworkRiskScore · integer | null

Maximum normalized network risk score allowed for real-time card authorizations. Scores range from 0 (lowest risk) to 999 (highest risk). Visa scores are normalized by multiplying the raw 0–99 score by 10. Scores equal to the ceiling are allowed. Authorizations without a score are also allowed. The lowest configured card or platform ceiling applies. Omit to preserve the current setting or send null to clear this scope.

Required range: 0 <= x <= 999

Example:

700

threeDSecurePassword · string

Sets a new static 3-D Secure password on the card. Send it on its own, and only when the card's cardCapabilities.supports3dSecurePassword is true.

Example:

"AbCd1234EfGh5678"

allowedMccs · string[] | null

Replacement list of merchant category codes the card may spend at. Supply null to allow every category not blocked, or omit to leave it unchanged. Rejected with INVALID_INPUT on a card whose issuer makes authorization decisions. Cannot be supplied alongside status: CLOSED. Changing or clearing this list does not loosen Lightspark's global, platform, or card controls: all configured allow lists intersect and all block lists combine.

Minimum array length: 1

Pattern: ^[0-9]{4}$

Example:

["5411"]

blockedMccs · string[] | null

Replacement list of merchant category codes the card declines. Supply null to clear it, or omit to leave it unchanged. On a card issued for an agent, Grid's default agent blocks still apply on top of this list; lift them with defaultMccBlocksLifted. Rejected with INVALID_INPUT on a card whose issuer makes authorization decisions. Cannot be supplied alongside status: CLOSED. Clearing this list removes only the card's own blocks; Lightspark's global, platform, and card controls still apply.

Pattern: ^[0-9]{4}$

Example:

["7995"]

defaultMccBlocksLifted · boolean

On a card issued for an agent, true lifts Grid's default agent merchant-category blocks and false restores them. Ignored on a card with no agent. Cannot be supplied alongside status: CLOSED. Lifting agent defaults does not remove other MCC restrictions.

Example:

true

Response

200

application/json

Card updated. Returns the updated card.

id · string · required

System-generated unique card identifier

Example:

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

customerId · string · required

The id of the Customer who holds this card.

Example:

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

status · enum<string> · required

Lifecycle status of a card.

Status	Description
PENDING_KYC	The cardholder has not yet completed KYC. Cards in this status cannot transact.
PROCESSING	The card has been requested and is being provisioned with the issuer.
PENDING_AUTH	The issuer has provisioned the card, but its USDB Embedded Wallet funding source lacks an active delegated signing key. Complete POST /auth/delegated-keys before using the card.
ACTIVE	The card is live and can authorize transactions.
FROZEN	The card is temporarily disabled by the platform or by Grid. New authorizations are declined with cardDeclinedReason: CARD_NOT_ACTIVE. Existing settlements and refunds continue to reconcile. A card Grid froze for review, or one frozen as COMPROMISED, cannot be unfrozen by the platform.
CLOSED	The card is permanently closed. Terminal, irreversible status.

Available options: PENDING_KYC, PROCESSING, PENDING_AUTH, 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

fundingSource · string · required

Internal account id that funds this card.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

createdAt · string<date-time> · required

Creation timestamp

Example:

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

updatedAt · string<date-time> · required

Last update timestamp

Example:

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

platformCardId · string

Platform-specific card identifier generated by the server.

Example:

"card-emp-001"

statusReason · enum<string>

Reason associated with the current status. Present when the card is PENDING_AUTH, CLOSED, or when provisioning was rejected; absent otherwise.

Available options: DELEGATION_REQUIRED, 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

pinStatus · enum<string>

State of the card's PIN. On the Card resource, this is the last known status and is present whenever PIN management is supported. An absent value means PIN management is unavailable for this card; it does not mean NOT_SET. Use GET /cards/{id} to retrieve pinStatus.

Status	Description
NOT_SET	No PIN has been set on the card. PIN verification is not enabled. Set one with POST /cards/{id}/set-pin or the hosted form returned by GET /cards/{id}/pin-entry-url.
OK	A PIN is set and usable.
BLOCKED	The PIN was entered incorrectly three consecutive times and is refused until cleared with POST /cards/{id}/pin/unblock, or replaced with POST /cards/{id}/set-pin.

Available options: NOT_SET, OK, BLOCKED

Example:

"OK"

pinUnblockAvailableAt · string<date-time> · read-only

Earliest time another PIN unblock attempt is allowed. Absent until the unblock allowance is used. Changing the PIN does not reset this time.

Example:

"2026-10-15T15:00:00Z"

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

cardCapabilities · object

Actions supported for this card by the issuer selected at issuance. Present for cards whose program has been resolved; absent otherwise. These capabilities are fixed at issuance for the card's lifetime.

Show child attributes

maxNetworkRiskScore · integer | null

Maximum normalized network risk score allowed for real-time card authorizations. Scores range from 0 (lowest risk) to 999 (highest risk). Visa scores are normalized by multiplying the raw 0–99 score by 10. Scores equal to the ceiling are allowed. Authorizations without a score are also allowed. The lowest configured card or platform ceiling applies. Null means no card-specific ceiling. Platform controls still apply.

Required range: 0 <= x <= 999

Example:

700

allowedMccs · string[]

The card's own merchant-category allow list. Absent when the card sets no allow list of its own. Lightspark's global, platform, and card controls also apply: spending must satisfy every configured allow list and no block list. This field does not include inherited restrictions.

Minimum array length: 1

Pattern: ^[0-9]{4}$

Example:

["5411"]

blockedMccs · string[]

Merchant category codes the card declines, with cardDeclinedReason: BLOCKED. Absent when the card blocks no category of its own. A card issued for an agent also declines Grid's default agent categories unless defaultMccBlocksLifted is true. Lightspark's global, platform, and card blocks apply in addition to this list and are not included in this field.

Pattern: ^[0-9]{4}$

Example:

["7995"]

agentId · string

The agent the card was issued for, when there is one.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

defaultMccBlocksLifted · boolean

Whether the platform lifted Grid's default agent merchant-category blocks on this card. Present only for a card issued for an agent.

Example:

false

lockedMerchant · object

The merchant a merchant-locked card (an agent's recurring purchase card) is locked to: the first merchant whose authorization on it was approved, the only one that can charge it. Absent until that first approved charge, and on every other card.

Show child attributes

currency · string

Currency the card transacts in, fixed at issuance by its card program. USDB-funded cards transact in USD, with funding converted at 1 USDB = 1 USD. Spending limits use the smallest unit of the card's currency (USD cents for USDB-funded cards). Changing the funding source does not change the card's currency or spending-limit units.

Example:

"USD"

processorRef · string

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.

Example:

"card_b81c2a4f"

issuerRef · string

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.

Example:

"lead_card_7a1b9c3d"