Skip to main content
POST
Ask for a stored card's details

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

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.

​
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.