Skip to main content
POST
Claim card session

Authorizations

Authorization
string
header
required

Bearer authentication: send your API key, agent key, or OAuth access token as Authorization: Bearer <credential>.

Headers

Idempotency-Key
string

Optional. Retrying the claim with the same key before expiresAt returns a new stand-in card and proxy login that expire at the same time as the first. Without a key, the credential can't be fetched again.

Maximum string length: 255
X-Instance-ID
string | null

Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money.

Maximum string length: 1024

Path Parameters

sessionId
string
required

Card session ID (csn_*).

Pattern: ^csn_[0-9a-f]{32}$

Query Parameters

customerPartyId
string

Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.

Pattern: ^pty_[0-9a-f]{32}$

Response

Successful Response

sessionId
string
required

Card session ID (csn_*).

cardId
string
required

The card the session uses: a Natural card you hold (pcd_) or a card the user added (eac_).

card
object
required
billingAddress
object | null
required

The card's billing address on file, for filling the merchant's checkout (the ZIP drives the bank's AVS check). For a virtual card, the address the bank holds for its cardholder. Null when there is none.

proxy
object
required
allowedHosts
string[]
required

Exact hostnames the proxy sends the real card to. The same as the session's allowedHosts.

expiresAt
string
required

RFC 3339 timestamp when the stand-in card and proxy login stop working. The same as the session's credentialExpiresAt.

Maximum string length: 64
instructions
string[]
required

Instructions for configuring and verifying the checkout proxy before paying.