Skip to main content
POST
/
cards
cURL
curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/cards \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardholderId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCardId": "card-emp-aary-001",
  "form": "VIRTUAL",
  "fundingSources": [
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
  ]
}
'
{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "cardholderId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "fundingSources": [
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000003"
  ],
  "createdAt": "2026-05-08T14:10:00Z",
  "updatedAt": "2026-05-08T14:11:00Z",
  "platformCardId": "card-emp-aary-001",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "panEmbedUrl": "https://embed.lithic.com/iframe/...?t=...",
  "currency": "USD",
  "issuerRef": "lithic_card_4f8d3a2b1c"
}

Documentation Index

Fetch the complete documentation index at: https://grid.lightspark.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
cardholderId
string
required

The id of the Customer to issue the card to. The customer must have KYC status APPROVED; otherwise the request is rejected with CARDHOLDER_KYC_NOT_APPROVED.

Example:

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

​
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 to bind as funding sources, in priority order. The first entry is tried first by Authorization Decisioning. Every card must be bound to at least one source, and every source must belong to the cardholder and be denominated in a card-eligible currency (USDB in v1); otherwise the request is rejected with FUNDING_SOURCE_INELIGIBLE.

Minimum array length: 1
Example:
[
  "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
]
​
platformCardId
string

Optional platform-specific card identifier. System-generated when omitted, mirroring platformCustomerId semantics.

Example:

"card-emp-aary-001"

Response

Card issued successfully

​
id
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.

StateDescription
PENDING_KYCThe cardholder has not yet completed KYC. Cards in this state cannot transact.
PENDING_ISSUEThe card has been requested and is being provisioned with the issuer.
ACTIVEThe card is live and can authorize transactions.
FROZENThe card is temporarily disabled by the platform. New authorizations are declined with CARD_PAUSED. Existing settlements and refunds continue to reconcile.
CLOSEDThe card is permanently closed. Terminal, irreversible state.
Available options:
PENDING_KYC,
PENDING_ISSUE,
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"
]
​
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

​
panEmbedUrl
string<uri>

URL of the card issuer's iframe that securely displays the PAN, CVV, and expiry to the cardholder. The full PAN and CVV never cross Grid's servers — render this URL in an iframe in your client to reveal card details.

Example:

"https://embed.lithic.com/iframe/...?t=..."

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

​
issuerRef
string
read-only

Opaque identifier for the card on the underlying issuer. Useful for cross-referencing in issuer dashboards; not used for any Grid request routing.

Example:

"lithic_card_4f8d3a2b1c"