Issue a card

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",
  "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
    platformCardId: 'card-emp-001',
    form: 'VIRTUAL',
    fundingSource: 'InternalAccount:019542f5-b3e7-1d02-0000-000000000002'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n  \"platformCardId\": \"card-emp-001\",\n  \"form\": \"VIRTUAL\",\n  \"fundingSource\": \"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/cards")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "status": "PENDING_KYC",
  "form": "VIRTUAL",
  "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "createdAt": "2026-05-08T14:10:00Z",
  "updatedAt": "2026-05-08T14:11:00Z",
  "platformCardId": "card-emp-001",
  "statusReason": "DELEGATION_REQUIRED",
  "brand": "VISA",
  "pinStatus": "OK",
  "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "cardCapabilities": {
    "supportsVelocityLimits": true,
    "supports3dSecurePassword": false,
    "supportsPanReveal": true,
    "supportsDigitalWalletTokenization": true
  },
  "maxNetworkRiskScore": 700,
  "allowedMccs": [
    "5411"
  ],
  "blockedMccs": [
    "7995"
  ],
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "defaultMccBlocksLifted": false,
  "lockedMerchant": {
    "descriptor": "BLUE BOTTLE COFFEE SF",
    "mcc": "5814",
    "city": "San Francisco",
    "state": "CA",
    "country": "US"
  },
  "currency": "USD",
  "processorRef": "card_b81c2a4f",
  "issuerRef": "lead_card_7a1b9c3d"
}

{
  "code": "INVALID_INPUT",
  "reason": "<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."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

{
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "reason": "<string>",
  "details": {}
}

Cards

Issue a card

Issue a new card for a cardholder. Every card is bound to one internal account, fundingSource, 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.

Configure card velocity limits through POST /card-velocity-limits. Omit cardId to set platform defaults before issuance, or supply the returned card id to set card-specific limits after issuance. Limits use the smallest unit of the card’s currency, including USD cents for USDB-funded USD cards.

If the 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 status do not count toward the limit.

New cards start in status: "PROCESSING" while the card issuer provisions the card. The card.status_change webhook fires on each status transition, including the transition to ACTIVE (or to CLOSED with statusReason: "ISSUER_REJECTED" if provisioning fails). A provisioned card funded by a USDB Embedded Wallet remains PENDING_AUTH with statusReason: "DELEGATION_REQUIRED" until all signed retries of POST /auth/delegated-keys are complete. Replacing USD funding with USDB without an active key, or revoking the required key, also moves an active card to PENDING_AUTH. Completing delegation or switching back to USD restores ACTIVE; frozen and closed cards keep their status.

POST

cards

Issue a card

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",
  "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
    platformCardId: 'card-emp-001',
    form: 'VIRTUAL',
    fundingSource: 'InternalAccount:019542f5-b3e7-1d02-0000-000000000002'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n  \"platformCardId\": \"card-emp-001\",\n  \"form\": \"VIRTUAL\",\n  \"fundingSource\": \"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/cards")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "status": "PENDING_KYC",
  "form": "VIRTUAL",
  "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "createdAt": "2026-05-08T14:10:00Z",
  "updatedAt": "2026-05-08T14:11:00Z",
  "platformCardId": "card-emp-001",
  "statusReason": "DELEGATION_REQUIRED",
  "brand": "VISA",
  "pinStatus": "OK",
  "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "cardCapabilities": {
    "supportsVelocityLimits": true,
    "supports3dSecurePassword": false,
    "supportsPanReveal": true,
    "supportsDigitalWalletTokenization": true
  },
  "maxNetworkRiskScore": 700,
  "allowedMccs": [
    "5411"
  ],
  "blockedMccs": [
    "7995"
  ],
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "defaultMccBlocksLifted": false,
  "lockedMerchant": {
    "descriptor": "BLUE BOTTLE COFFEE SF",
    "mcc": "5814",
    "city": "San Francisco",
    "state": "CA",
    "country": "US"
  },
  "currency": "USD",
  "processorRef": "card_b81c2a4f",
  "issuerRef": "lead_card_7a1b9c3d"
}

{
  "code": "INVALID_INPUT",
  "reason": "<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."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

{
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "reason": "<string>",
  "details": {}
}

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

fundingSource

string

required

Internal account id that funds this card. The account must belong to the customer and be denominated in a card-eligible currency; otherwise the request is rejected with INVALID_INPUT.

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"

cardholder

object

The person to issue a BUSINESS customer's card to. The card spends from the business's account and carries this person's name and contact details. Omit it to issue the card to the business itself. Rejected with INVALID_INPUT for an INDIVIDUAL customer, for an address that is not a complete United States address, and together with agentId, whose agent names its own person.

Show child attributes

maxNetworkRiskScore

integer

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. Omit to set no card-specific ceiling.

Required range: 0 <= x <= 999

Example:

700

allowedMccs

string[]

Merchant category codes the card may spend at. Omit to allow every category not blocked. Rejected with INVALID_INPUT on a card program where the card issuer makes authorization decisions. Lightspark's global, platform, and card controls also apply. Every configured allow list must admit the category, and any block list can refuse it; this list cannot loosen those controls.

Minimum array length: 1

Pattern: ^[0-9]{4}$

Example:

["5411"]

blockedMccs

string[]

Merchant category codes the card declines. Rejected with INVALID_INPUT on a card program where the card issuer makes authorization decisions. Blocks at all scopes combine and take precedence over any allow list.

Pattern: ^[0-9]{4}$

Example:

["7995"]

agentId

string

Issue the card for this agent, which must belong to the same customer. The agent can then read the card, tighten its merchant categories, and freeze it through /agents/me/cards. Grid's default agent merchant-category blocks apply in addition to blockedMccs until the platform lifts them with PATCH /cards/{id} and defaultMccBlocksLifted: true. The card's spend counts against the agent's policy as its sends do: each authorization must fit the per-transaction, daily and monthly limits and the daily transaction count, and is declined while the agent is paused.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

Response

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.

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"

status

enum<string>

required

Lifecycle status of a card.

Status	Description
`PENDING_KYC`	The cardholder has not yet completed KYC. Cards in this status cannot transact.
`PROCESSING`	The card has been requested and is being provisioned with the issuer.
`PENDING_AUTH`	The 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.
`ACTIVE`	The card is live and can authorize transactions.
`FROZEN`	The 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.
`CLOSED`	The card is permanently closed. Terminal, irreversible status.

Available options:

PENDING_KYC,

PROCESSING,

PENDING_AUTH,

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"

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"

statusReason

enum<string>

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

Available options:

DELEGATION_REQUIRED,

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

pinStatus

enum<string>

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.

Status	Description
`NOT_SET`	No 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`.
`OK`	A PIN is set and usable.
`BLOCKED`	The 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`.

Available options:

NOT_SET,

OK,

BLOCKED

Example:

"OK"

pinUnblockAvailableAt

string<date-time>

read-only

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

Example:

"2026-10-15T15:00:00Z"

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

maxNetworkRiskScore

integer | null

Required range: 0 <= x <= 999

Example:

700

allowedMccs

string[]

The card's own merchant-category allow list. Absent when the card sets no allow list of its own. Lightspark's global, platform, and card controls also apply: spending must satisfy every configured allow list and no block list. This field does not include inherited restrictions.

Minimum array length: 1

Pattern: ^[0-9]{4}$

Example:

["5411"]

blockedMccs

string[]

Merchant category codes the card declines, with cardDeclinedReason: BLOCKED. Absent when the card blocks no category of its own. A card issued for an agent also declines Grid's default agent categories unless defaultMccBlocksLifted is true. Lightspark's global, platform, and card blocks apply in addition to this list and are not included in this field.

Pattern: ^[0-9]{4}$

Example:

["7995"]

agentId

string

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

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

defaultMccBlocksLifted

boolean

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

Example:

false

lockedMerchant

object

The merchant a merchant-locked card (an agent's recurring purchase card) is locked to: the first merchant whose authorization on it was approved, the only one that can charge it. Absent until that first approved charge, and on every other card.

Show child attributes

currency

string

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.

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

Issue a card

Authorizations

Headers

Body

Response