Issue a card

Issue a new card for a cardholder. Every card must be bound to at least one funding source at create time. The cardholder must have KYC status APPROVED before a card can be issued; otherwise the request is rejected with CARDHOLDER_KYC_NOT_APPROVED.

Card issuance is fee-bearing and cannot be reversed, so an Idempotency-Key header is required. Retries must carry the same key.

Optional maxSpendPerTransaction, maxSpendPerDay, and maxTransactionsPerDay values set the card-specific caps on one transaction, on spend during one UTC calendar day, and on the number of transactions during one UTC calendar day. Check the funding-source internal account’s cardCapabilities.supportsSpendLimits before supplying either spend limit, and cardCapabilities.supportsTransactionCountLimit before supplying the transaction count limit. If the platform config sets the corresponding cardConfigs value, Grid enforces the lower of the card and platform caps. Amounts use the smallest unit of the card’s currency.

If any funding source is an Embedded Wallet internal account, the cardholder must authorize Grid to sign Spark token transactions for that card funding source by completing the delegated-key creation flow with POST /auth/delegated-keys. Until an active delegated key exists for that funding source, Authorization Decisioning cannot use it to fund card transactions.

A platform may be limited to a maximum number of live cards. Once that limit is reached, further issuance is rejected with CARD_LIMIT_REACHED until a card is closed or Lightspark raises the limit. Cards in CLOSED state do not count toward the limit.

New cards start in state: "PROCESSING" while the card issuer provisions the card. The card.state_change webhook fires on each state transition, including the transition to ACTIVE (or to CLOSED with stateReason: "ISSUER_REJECTED" if provisioning fails).

POST /cards

cURL

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/cards \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCardId": "card-emp-001",
  "form": "VIRTUAL",
  "fundingSources": [
    "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
  ],
  "maxSpendPerTransaction": 5000,
  "maxSpendPerDay": 25000,
  "maxTransactionsPerDay": 20
}
'

201

{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "customerId": "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,
  "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"
}

Authorizations

Authorization · string · header · required

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

Headers

Idempotency-Key · string · required

A unique identifier for the request, up to 255 characters. A retry carrying the same key returns the card created by the first request; reusing a key for a materially different card request is rejected with 409.

Maximum string length: 255

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

customerId · 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 selects the card issuer and therefore the card's capabilities. 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; otherwise the request is rejected with FUNDING_SOURCE_INELIGIBLE.

Minimum array length: 1

Example:

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

platformCardId · string

Platform-specific card identifier. Always generated by the server; any value supplied in the request is ignored.

Example:

"card-emp-001"

threeDSecurePassword · string

Static password used as the card's 3-D Secure factor. Required when the first funding-source internal account's cardCapabilities.supports3dSecurePassword is true; omitting it or supplying an empty or whitespace-only string is rejected with INVALID_INPUT. When the capability is false, supplying this field is rejected with INVALID_INPUT because cards in that program have no static-password factor. Grid does not retain the value: it is forwarded to the issuer and discarded, so it cannot be read back afterwards; a cardholder who forgets it must set a new one through PATCH /cards/{id}.

Example:

"AbCd1234EfGh5678"

maxSpendPerTransaction · integer<int64>

Optional card-specific cap on a single transaction, in the smallest unit of the card currency derived from its funding sources. Omit this field for no card-specific cap. When the platform config also supplies cardConfigs.maxSpendPerTransaction, Grid enforces the lower of the two values. Accepted only when the funding-source internal account's cardCapabilities.supportsSpendLimits is true. A transaction for exactly the effective limit is allowed.

Required range: 1 <= x <= 9007199254740991

Example:

5000

maxSpendPerDay · integer<int64>

Optional card-specific cap on cumulative new spend during one UTC calendar day, in the smallest unit of the card currency derived from its funding sources. Omit this field for no card-specific daily cap. When the platform config also supplies cardConfigs.maxSpendPerDay, Grid enforces the lower of the two values. The window resets at 00:00 UTC, and refunds, reversals, and authorization expiries do not restore capacity during the day. Accepted only when the funding-source internal account's cardCapabilities.supportsSpendLimits is true. Spend exactly equal to the effective limit is allowed.

Required range: 1 <= x <= 9007199254740991

Example:

25000

maxTransactionsPerDay · integer<int32>

Optional card-specific cap on the number of transactions the card may authorize during one UTC calendar day. Omit this field for no card-specific daily transaction cap. When the platform config also supplies cardConfigs.maxTransactionsPerDay, Grid enforces the lower of the two values. The window resets at 00:00 UTC. Each approved authorization counts once; refunds, reversals, and authorization expiries do not restore capacity during the day. Accepted only when the funding-source internal account's cardCapabilities.supportsTransactionCountLimit is true.

Required range: 1 <= x <= 2147483647

Example:

20

Response

201

application/json

Card created successfully. Newly-created cards start in PROCESSING while the issuer provisions them. Cards funded by an Embedded Wallet internal account also require an active delegated key for that funding source before Authorization Decisioning can use it.

id · string · required · read-only

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

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

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