Hand a deleted agent's card to an agent

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/card-handover \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'POST', headers: {Authorization: 'Basic <encoded-value>'}};

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

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/card-handover")
  .post(null)
  .addHeader("Authorization", "Basic <encoded-value>")
  .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",
  "maxSpendPerTransaction": 5000,
  "maxSpendPerDay": 25000,
  "maxTransactionsPerDay": 20,
  "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": {
    "supportsSpendLimits": true,
    "supportsSpendLimitsAtIssuance": true,
    "supportsTransactionCountLimit": true,
    "supports3dSecurePassword": false,
    "supportsPanReveal": true,
    "supportsDigitalWalletTokenization": true
  },
  "maxNetworkRiskScore": 700,
  "allowedMccs": [
    "5411"
  ],
  "blockedMccs": [
    "7995"
  ],
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "defaultMccBlocksLifted": false,
  "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"
    ]
  }
}

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

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

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

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

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

Agent Management

Hand a deleted agent's card to an agent

Move the customer’s standard agent card that Grid froze when the agent it was issued for was deleted to this agent, and unfreeze it. Use this when a customer reconnects agent software whose agent the platform deleted: a frozen card still counts against the customer’s card limit, so without a hand-over the customer can neither use it nor be issued another.

A card qualifies only while the freeze Grid placed on its agent’s deletion is the only reason it is frozen. A card frozen by the platform, the customer, an agent or Lightspark is left as it is, and purchase cards are never handed over. The agent must belong to the card’s customer, must be neither paused nor deleted, must have a policy granting MANAGE_CARDS, and must hold no standard card that is not CLOSED. When several cards qualify, the most recently issued one is handed over.

The customer must still meet what issuing a card requires: an individual customer with approved KYC who has accepted the cardholder agreement. The card is unfrozen as a platform status: ACTIVE update is, so the platform receives the same card status webhook; a card whose funding authorization is missing comes back PENDING_AUTH. A card that was still being provisioned when its agent was deleted is not handed over. Responds 204 when the customer has no card to hand over.

POST

agents

{agentId}

card-handover

Hand a deleted agent's card to an agent

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/card-handover \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'POST', headers: {Authorization: 'Basic <encoded-value>'}};

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

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/card-handover")
  .post(null)
  .addHeader("Authorization", "Basic <encoded-value>")
  .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",
  "maxSpendPerTransaction": 5000,
  "maxSpendPerDay": 25000,
  "maxTransactionsPerDay": 20,
  "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": {
    "supportsSpendLimits": true,
    "supportsSpendLimitsAtIssuance": true,
    "supportsTransactionCountLimit": true,
    "supports3dSecurePassword": false,
    "supportsPanReveal": true,
    "supportsDigitalWalletTokenization": true
  },
  "maxNetworkRiskScore": 700,
  "allowedMccs": [
    "5411"
  ],
  "blockedMccs": [
    "7995"
  ],
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "defaultMccBlocksLifted": false,
  "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"
    ]
  }
}

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

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

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

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

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

Authorizations

Authorization

string

header

required

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

Path Parameters

agentId

string

required

System-generated unique agent identifier

Query Parameters

previousAgentId

string

Hand over only a card issued for this deleted agent, such as the one the customer's previous connection of the same agent software held. Omit it to consider every deleted agent of the customer.

Response

The card now belongs to the agent and is no longer frozen

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"

maxSpendPerTransaction

integer<int64> | null

required

The largest amount this card can authorize on a single transaction, in the smallest unit of its currency (cents for USD). An authorization for exactly the limit is allowed. A later clearing can still settle above it — a restaurant tip, for example — so this caps the authorization, not the final settled amount. null means the card sets no limit of its own. If your platform config also sets cardConfigs.maxSpendPerTransaction (the platform-level limit), the lower of the two applies and this value stays as you set it.

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

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

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.

Required range: 0 <= x <= 999

Example:

700

allowedMccs

string[]

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.

Minimum array length: 1

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

Example:

["5411"]

blockedMccs

string[]

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.

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

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

Hand a deleted agent's card to an agent

Authorizations

Path Parameters

Query Parameters

Response