Get a card

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/cards/{id} \
  --header 'Authorization: Basic <encoded-value>'

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.retrieve('id');

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.CardRetrieveParams

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

    val card: Card = client.cards().retrieve("id")
}

{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "cardholderId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "state": "PENDING_KYC",
  "form": "VIRTUAL",
  "fundingSources": [
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000003"
  ],
  "maxSpendPerTransaction": 5000,
  "maxSpendPerDay": 25000,
  "createdAt": "2026-05-08T14:10:00Z",
  "updatedAt": "2026-05-08T14:11:00Z",
  "platformCardId": "card-emp-aary-001",
  "stateReason": "ISSUER_REJECTED",
  "brand": "VISA",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "currency": "USD",
  "processorRef": "card_b81c2a4f",
  "issuerRef": "lead_card_7a1b9c3d"
}

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

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

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

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

GET

cards

{id}

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/cards/{id} \
  --header 'Authorization: Basic <encoded-value>'

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.retrieve('id');

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.CardRetrieveParams

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

    val card: Card = client.cards().retrieve("id")
}

{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "cardholderId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "state": "PENDING_KYC",
  "form": "VIRTUAL",
  "fundingSources": [
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000003"
  ],
  "maxSpendPerTransaction": 5000,
  "maxSpendPerDay": 25000,
  "createdAt": "2026-05-08T14:10:00Z",
  "updatedAt": "2026-05-08T14:11:00Z",
  "platformCardId": "card-emp-aary-001",
  "stateReason": "ISSUER_REJECTED",
  "brand": "VISA",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "currency": "USD",
  "processorRef": "card_b81c2a4f",
  "issuerRef": "lead_card_7a1b9c3d"
}

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

{
  "status": 404,
  "code": "TRANSACTION_NOT_FOUND",
  "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

Response

Successful operation

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

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"
]

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

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

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"

processorRef

string

read-only

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

read-only

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

Authorizations

Path Parameters

Response