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 single-use purchase cards are never handed over.

With kind=PURCHASE, the newest qualifying recurring purchase card is handed over instead; call again until 204 to move each of them. It is available only where the platform enables recurring purchase cards. The agent must also hold an active delegated key on the Embedded Wallet that funds the card, which pays for the card from then on; a card on a wallet where it holds none is not handed over. The agent may hold a standard card, but must have room under the platform’s limit on open recurring purchase cards, counting those awaiting approval; otherwise the request is rejected with PURCHASE_CARD_LIMIT_REACHED.

The agent must belong to the card’s customer, must be neither paused nor deleted, and must have a policy granting MANAGE_CARDS. For a standard card it must also 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

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

200

{
  "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"
}

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.

kind · enum<string>

The kind of card to hand over: STANDARD (the default) or PURCHASE for a recurring purchase card. How an agent card is used and funded.

Kind	Description
STANDARD	A card issued for the agent, by the platform with POST /cards or by the agent with POST /agents/me/cards. The customer holds the card details and its spend comes from the customer's account; that spend counts against the agent's policy limits as the agent's sends do. The agent can read the card, tighten its merchant categories, and freeze it.
PURCHASE	A single-use virtual card the agent issued for one online purchase with POST /agents/me/cards. It is funded from the customer's Embedded Wallet, its spend counts against the agent's policy limits, and it closes after its first approved authorization or when it expires unused. A recurring purchase card (purchase.recurring) is instead locked to the first merchant that charges it, may be charged there again up to its monthly limit, and stays open until it is closed. The agent reads its number, expiry and CVV through POST /agents/me/cards/{cardId}/reveal.

Available options: STANDARD, PURCHASE

Response

200

application/json

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

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

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[]

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"