Ask for a stored card's details

Ask to use a stored card for one purchase. The agent names the merchant, the amount it expects to be charged and what the purchase is; Grid cannot enforce the amount, since the merchant charges the customer’s own card.

The customer approves every use unless they chose to auto-approve this agent at this merchant up to the amount. A use that waits answers 202 with a USE_STORED_CARD action in PENDING_APPROVAL; once it is APPROVED, call again with only its actionId to collect the link. A use with needsCvc always waits, since the customer enters the security code when approving.

An approved use answers 200 with a single-use detailsUrl, valid for five minutes. The number reaches the agent through Evervault’s Relay, which decrypts it on the way; Grid never sends it. Open the URL once, right away, where the purchase is being made, and never store or log it. Each approved use issues one link: asking again with the same actionId is refused with 409.

Every use is audit-logged with the agent as the actor. Uses are rate limited per card, per agent and per customer; beyond the limit the request is rejected with 429 RATE_LIMITED. Requires the USE_STORED_CARDS permission and the customer’s permission for this agent to use the card.

POST /agents/me/stored-cards/{storedCardId}/reveal

Ask for a stored card's details

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/stored-cards/{storedCardId}/reveal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "actionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "merchant": "example-store.com",
  "amount": 4999,
  "currency": "USD",
  "purpose": "Running shoes, size 10",
  "needsCvc": true
}
'

200

{
  "detailsUrl": "https://relay.example.com/grid/2025-10-13/stored-card-reveals/abc",
  "expiresAt": "2026-11-06T15:05:00Z",
  "actionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "cvcIncluded": false,
  "card": {
    "lastFour": "0005",
    "brand": "VISA",
    "funding": "CREDIT",
    "expiryMonth": 8,
    "expiryYear": 2029,
    "id": "StoredCard:019542f5-b3e7-1d02-0000-000000000077",
    "issuerCountry": "US",
    "nickname": "Personal Visa"
  },
  "holderName": "Jane Doe",
  "billingAddress": {
    "line1": "123 Main Street",
    "postalCode": "94105",
    "country": "US",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA"
  }
}

Authorizations

Authorization · string · header · required

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Path Parameters

storedCardId · string · required

System-generated unique stored card identifier

Body

application/json

Either the purchase the agent wants the card for (merchant, amount, currency, purpose and optionally needsCvc), or actionId alone, to collect the link for a use the customer has since approved.

actionId · string

An APPROVED USE_STORED_CARD action of this agent for this card whose link has not been issued yet. Sent alone.

Maximum string length: 64

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000099"

merchant · string

Where the card will be used: the merchant's website host (for example example-store.com) or name. Shown to the customer and used to match merchants they chose to auto-approve. Supplied by the agent and not verified by Grid.

Required string length: 1 - 255

Example:

"example-store.com"

amount · integer<int64>

The amount the agent expects to be charged, in the smallest unit of currency. Shown to the customer. Grid cannot enforce it: the charge is made by the merchant on the customer's own card.

Required range: x >= 1

Example:

4999

currency · string

ISO 4217 code of amount.

Required string length: 3

Example:

"USD"

purpose · string

What the purchase is, shown to the customer.

Required string length: 1 - 255

Example:

"Running shoes, size 10"

needsCvc · boolean

Whether the checkout asks for the card's security code. Grid never stores it, so the customer enters it when approving: a use with needsCvc always waits for approval.

Example:

true

Response

200

application/json

Link issued

A single-use link to the card's details. Open detailsUrl once, right away, where the purchase is being made; it answers once and expires at expiresAt. The number reaches the agent through Evervault's Relay, which decrypts it on the way: Grid never sends it. Never store or log the URL or what it returns.

detailsUrl · string<uri> · required

The single-use link. It answers JSON with number, expiryMonth, expiryYear, holderName and, when cvcIncluded, cvc.

Maximum string length: 2048

Example:

"https://relay.example.com/grid/2025-10-13/stored-card-reveals/abc"

expiresAt · string<date-time> · required

When the link stops working, five minutes after it is issued.

Example:

"2026-11-06T15:05:00Z"

actionId · string · required

The USE_STORED_CARD action that records this use.

Maximum string length: 64

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000099"

cvcIncluded · boolean · required

Whether the link also returns the security code the customer entered when approving.

Example:

false

card · object · required

A stored card the agent may use: its display fields only. The number is reached only through POST /agents/me/stored-cards/{storedCardId}/reveal.

Show child attributes

holderName · string · required

The name on the card, for the checkout form.

Maximum string length: 255

Example:

"Jane Doe"

billingAddress · object · required

The card's billing address, for the checkout form.

Show child attributes