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"
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const card = await client.cards.update('id', { state: 'FROZEN' });

console.log(card.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.cards.Card
import com.lightspark.grid.models.cards.CardUpdateParams
import com.lightspark.grid.models.cards.CardUpdateRequest

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: CardUpdateParams = CardUpdateParams.builder()
        .id("id")
        .cardUpdateRequest(CardUpdateRequest.builder().build())
        .build()
    val card: Card = client.cards().update(params)
}

{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "state": "PENDING_KYC",
  "form": "VIRTUAL",
  "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "maxSpendPerTransaction": 5000,
  "maxSpendPerDay": 25000,
  "maxTransactionsPerDay": 20,
  "createdAt": "2026-05-08T14:10:00Z",
  "updatedAt": "2026-05-08T14:11:00Z",
  "platformCardId": "card-emp-001",
  "stateReason": "ISSUER_REJECTED",
  "brand": "VISA",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "cardCapabilities": {
    "supportsSpendLimits": true,
    "supportsTransactionCountLimit": true,
    "supports3dSecurePassword": false,
    "supportsPanReveal": true
  },
  "currency": "USD",
  "processorRef": "card_b81c2a4f",
  "issuerRef": "lead_card_7a1b9c3d"
}

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "code": "TRANSACTION_NOT_FOUND",
  "message": "<string>",
  "details": {}
}

{
  "status": 409,
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "code": "GRID_SWITCH_ERROR",
  "message": "<string>",
  "details": {}
}

{
  "status": 501,
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "message": "<string>",
  "details": {}
}

Cards

Update a card

Update a card’s state, bound fundingSource, and / or maxSpendPerTransaction, maxSpendPerDay, or maxTransactionsPerDay. At least one field 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.
fundingSource, when supplied, replaces the card’s bound internal account. It must belong to the customer and be denominated in the card’s currency. fundingSource cannot be supplied alongside state: CLOSED. On card programs where the card issuer makes authorization decisions, fundingSource cannot be combined with any state change, so send the changes as separate requests. On card programs where Grid makes the authorization decision, the combination remains valid for state changes other than CLOSED.
maxSpendPerTransaction, when supplied, replaces the card-specific per-transaction cap. Supply a positive integer in the smallest unit of the card’s currency to set it or null to clear it. If the platform config sets cardConfigs.maxSpendPerTransaction, Grid enforces the lower of the card and platform values. The card’s cardCapabilities.supportsSpendLimits must be true. maxSpendPerTransaction cannot be supplied alongside state: CLOSED.
maxSpendPerDay, when supplied, replaces the card-specific cap on cumulative new spend during one UTC calendar day. Supply a positive integer in the smallest unit of the card’s currency to set it or null to clear it. If the platform config sets cardConfigs.maxSpendPerDay, Grid enforces the lower of the card and platform values. Refunds, reversals, and authorization expiries do not restore capacity during the day. The card’s cardCapabilities.supportsSpendLimits must be true. maxSpendPerDay cannot be supplied alongside state: CLOSED.
maxTransactionsPerDay, when supplied, replaces the card-specific cap on the number of transactions the card may authorize during one UTC calendar day. Supply a positive integer to set it or null to clear it. If the platform config sets cardConfigs.maxTransactionsPerDay, Grid enforces the lower of the card and platform values. Refunds, reversals, and authorization expiries do not restore capacity during the day. maxTransactionsPerDay requires the card’s cardCapabilities.supportsTransactionCountLimit to be true and cannot be supplied alongside state: 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:

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. 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.state_change webhook fires on every successful state transition.

PATCH

cards

{id}

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"
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const card = await client.cards.update('id', { state: 'FROZEN' });

console.log(card.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.cards.Card
import com.lightspark.grid.models.cards.CardUpdateParams
import com.lightspark.grid.models.cards.CardUpdateRequest

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: CardUpdateParams = CardUpdateParams.builder()
        .id("id")
        .cardUpdateRequest(CardUpdateRequest.builder().build())
        .build()
    val card: Card = client.cards().update(params)
}

{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "state": "PENDING_KYC",
  "form": "VIRTUAL",
  "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "maxSpendPerTransaction": 5000,
  "maxSpendPerDay": 25000,
  "maxTransactionsPerDay": 20,
  "createdAt": "2026-05-08T14:10:00Z",
  "updatedAt": "2026-05-08T14:11:00Z",
  "platformCardId": "card-emp-001",
  "stateReason": "ISSUER_REJECTED",
  "brand": "VISA",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "cardCapabilities": {
    "supportsSpendLimits": true,
    "supportsTransactionCountLimit": true,
    "supports3dSecurePassword": false,
    "supportsPanReveal": true
  },
  "currency": "USD",
  "processorRef": "card_b81c2a4f",
  "issuerRef": "lead_card_7a1b9c3d"
}

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "code": "TRANSACTION_NOT_FOUND",
  "message": "<string>",
  "details": {}
}

{
  "status": 409,
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "code": "GRID_SWITCH_ERROR",
  "message": "<string>",
  "details": {}
}

{
  "status": 501,
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

System-generated unique card identifier

Body

application/json

Update request for PATCH /cards/{id}. At least one of state, fundingSource, maxSpendPerTransaction, maxSpendPerDay, or maxTransactionsPerDay 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 fundingSource, maxSpendPerTransaction, maxSpendPerDay, or maxTransactionsPerDay.

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"

fundingSource

string

Replaces the card's funding source. Must belong to the customer and be denominated in the card's currency. Cannot be supplied alongside state: CLOSED. To stop a card from spending, set state: FROZEN instead.

Example:

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

maxSpendPerTransaction

integer<int64> | null

Replacement card-specific per-transaction cap, in the smallest unit of the card's currency. Omit this field to leave the current cap unchanged, supply null to clear it, or supply a positive integer to set it. When the platform config also supplies cardConfigs.maxSpendPerTransaction, Grid enforces the lower of the two values. Accepted only when the card's cardCapabilities.supportsSpendLimits is true. Cannot be supplied alongside state: CLOSED.

Required range: 1 <= x <= 9007199254740991

Example:

10000

maxSpendPerDay

integer<int64> | null

Replacement card-specific UTC-calendar-day cap, in the smallest unit of the card's currency. Omit this field to leave the current cap unchanged, supply null to clear it, or supply a positive integer to set it. When the platform config also supplies cardConfigs.maxSpendPerDay, Grid enforces the lower of the two values. Refunds, reversals, and authorization expiries do not restore capacity during the day. Accepted only when the card's cardCapabilities.supportsSpendLimits is true. Cannot be supplied alongside state: CLOSED.

Required range: 1 <= x <= 9007199254740991

Example:

25000

maxTransactionsPerDay

integer<int32> | null

Replacement card-specific cap on the number of transactions the card may authorize during one UTC calendar day. Omit this field to leave the current cap unchanged, supply null to clear it, or supply a positive integer to set it. When the platform config also supplies cardConfigs.maxTransactionsPerDay, Grid enforces the lower of the two values. Refunds, reversals, and authorization expiries do not restore capacity during the day. Accepted only when the card's cardCapabilities.supportsTransactionCountLimit is true. Cannot be supplied alongside state: CLOSED.

Required range: 1 <= x <= 2147483647

Example:

20

Response

Card updated. Returns the updated card.

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"

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.
`PROCESSING`	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,

PROCESSING,

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"

maxSpendPerTransaction

integer<int64> | null

required

Card-specific cap on a single transaction, in the smallest unit of the card's currency. Null means the card has no card-specific cap. When the platform config also supplies cardConfigs.maxSpendPerTransaction, Grid enforces the lower of the two values without replacing this configured value. A transaction for exactly the effective limit is allowed.

Required range: 1 <= x <= 9007199254740991

Example:

5000

maxSpendPerDay

integer<int64> | null

required

Card-specific cap on cumulative new spend during one UTC calendar day, in the smallest unit of the card's currency. The window resets at 00:00 UTC. Null means the card has no card-specific daily cap. When the platform config also supplies cardConfigs.maxSpendPerDay, Grid enforces the lower of the two values without replacing this configured value. Refunds, reversals, and authorization expiries do not restore capacity during the day. Spend exactly equal to the effective limit is allowed.

Required range: 1 <= x <= 9007199254740991

Example:

25000

maxTransactionsPerDay

integer<int32> | null

required

Card-specific cap on the number of transactions the card may authorize during one UTC calendar day. The window resets at 00:00 UTC. Null means the card has no card-specific daily transaction cap. When the platform config also supplies cardConfigs.maxTransactionsPerDay, Grid enforces the lower of the two values without replacing this configured value. Each approved authorization counts once for the day it was authorized; refunds, reversals, and authorization expiries do not restore capacity during the day. A transaction that brings the day's count exactly to the effective limit is allowed.

Required range: 1 <= x <= 2147483647

Example:

20

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"

stateReason

enum<string>

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

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

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

currency

string

Currency the card transacts in (ISO 4217 for fiat, tickers for crypto). Derived from the funding source at issue time.

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"

Using the API

API documentation

Update a card

Authorizations

Path Parameters

Body

Response