LIlightsparkdev
Cards

Get a card

Changed on

Retrieve a card by its system-generated id. To display the card's full PAN, CVV, and expiry to the cardholder, request a reveal with POST /cards/{id}/reveal — the card resource itself never carries the reveal URL.

get/cards/{id}

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/cards/{id}
  • Auth
    HTTP basic

Response

Successful operation

idstring required

System-generated unique card identifier

customerIdstring required

The id of the Customer who holds this card.

platformCardIdstring

Platform-specific card identifier generated by the server.

status'PENDING_KYC' | 'PROCESSING' | 'PENDING_AUTH' | 'ACTIVE' | 'FROZEN' | 'CLOSED' required

Lifecycle status of a card.

StatusDescription
PENDING_KYCThe cardholder has not yet completed KYC. Cards in this status cannot transact.
PROCESSINGThe card has been requested and is being provisioned with the issuer.
PENDING_AUTHThe 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.
ACTIVEThe card is live and can authorize transactions.
FROZENThe 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.
CLOSEDThe card is permanently closed. Terminal, irreversible status.
statusReason'DELEGATION_REQUIRED' | 'ISSUER_REJECTED' | 'CLOSED_BY_PLATFORM' | 'CLOSED_BY_GRID'

Reason a card reached a terminal or non-active status. Present on PENDING_AUTH and CLOSED cards, and on cards that fail provisioning before reaching ACTIVE.

ReasonDescription
DELEGATION_REQUIREDThe card funding source has no usable delegated signing key. Present while the card is PENDING_AUTH.
ISSUER_REJECTEDThe card issuer rejected provisioning during PROCESSING.
CLOSED_BY_PLATFORMThe card was closed via PATCH /cards/{id} (status: CLOSED) by the platform.
CLOSED_BY_GRIDThe card was closed by Grid (e.g. compliance or risk action).
brand'VISA' | 'MASTERCARD'

Card network brand. Read-only — determined by Grid when the card is provisioned with the issuer.

form'VIRTUAL' required

Physical form factor of the card. Only VIRTUAL is supported in v1; PHYSICAL will be added in a later release.

pinStatus'NOT_SET' | 'OK' | 'BLOCKED'

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.

StatusDescription
NOT_SETNo 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.
OKA PIN is set and usable.
BLOCKEDThe 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.
pinUnblockAvailableAtstring date-time

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

last4string

Last four digits of the card PAN.

expMonthinteger

Card expiration month (1–12).

expYearinteger

Card expiration year (four digits).

fundingSourcestring required

Internal account id that funds this card.

maxNetworkRiskScoreinteger nullable

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.

allowedMccsstring[]

Merchant category codes the card may spend at. Present only on a card issued for an agent; absent when that card may spend at any category not blocked.

blockedMccsstring[]

Merchant category codes a card issued for an agent declines, with cardDeclinedReason: BLOCKED. Present only on such a card, which also declines Grid's default agent categories unless defaultMccBlocksLifted is true.

agentIdstring

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

defaultMccBlocksLiftedboolean

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

currencystring

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.

processorRefstring

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.

issuerRefstring

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.

createdAtstring date-time required

Creation timestamp

updatedAtstring date-time required

Last update timestamp

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

  • 5fbda612feb8Revision changes
    • 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

    • info

      added the required property / to the response with the status

  • 5547c7aba40eRevision changes
    • info

      added the optional property to the response with the status