Card checkout rail

Use scoped cards
with agent sessions

Scoped cards let an approved agent session make budget-limited card payments at merchants that do not support x402 or wallet transfers. A card can be used for multiple purchases until its approved limit is reached, or until it expires or is canceled. The card program is consumer-facing, issuer-managed, and backed by the user's own stablecoin reserve.

issuer-managed User KYC Stablecoin reserve Lifetime limit

Before card sessions

Complete application, KYC, and reserve first

Cards use a separate card setup path. The user must create the card application, complete issuer-managed KYC, and fund the card reserve before an agent can issue a scoped card.

Review prerequisites

Model and ownership

Scoped cards are not a replacement for the regular Passport wallet. They are a separate card payment rail for merchant checkouts that require a virtual card.

Layer	Owns	Does not own
User	Application consent, card KYC, reserve funding, and session approval.	Card network processing or issuer risk decisions.
Passport	Cards UI, user-to-issuer profile mapping, agent session authorization, local card metadata, webhook projection, and activity display.	KYC adjudication, card network authorization, or custody of card collateral.
card issuer	Consumer application, KYC workflow, card issuing, authorization, settlement lifecycle, balances, and webhooks.	Passport agent session policy or user-facing agent approval UX.
Agent checkout executor	Presents the issued card to the merchant checkout under the approved session boundary.	Changing the user's card budget or using the card after completion.

V1 shape

Cards are agent-first, session-bound, and budget-limited. A card can be reused while approved budget remains, but it should not be kept as a general card-on-file credential.

Prerequisites

Cards have a longer setup path than x402 because the user is applying for an issuer-managed consumer card program and funding a separate reserve.

Create the card application

Open the Cards page in Passport and start setup. Passport creates or resumes the card application and stores the issuer profile id for future card operations.

Complete issuer-managed KYC

Passport sends the user to the hosted KYC link. The issuer owns the identity verification decision. Passport only mirrors the resulting status, such as pending, action required, approved, locked, canceled, or exempt.

Fund the card reserve

The card reserve is separate from the normal Passport wallet. Add supported stablecoin to the card reserve deposit address shown on the Cards page. Passport displays card balances and supported chain/token rows.

Approve a card session

The agent requests a session with card execution enabled. The user reviews the amount, expiry, and task summary before passkey approval.

Supported reserve assets

Fund the card reserve with USDC on any chain the Passport multichain wallet supports — currently Base, Solana, and Tempo.

End-to-end flow

The user completes Cards setup and card KYC.
The user funds the card reserve with supported stablecoin.
The agent asks for a card-capable session with --use-card.
The user opens the approval URL and approves with passkey.
Passport creates a scoped card for the approved session budget.
The controlled checkout executor presents the card to the merchant checkout.
The issuer sends transaction and card webhooks. Passport projects activity and card status.
Passport accumulates settled spend and marks the card completed when its approved budget is exhausted.

bash

$ kpass agent:session create \
    --task-summary 'Buy one item from a card-only merchant' \
    --max-amount-per-tx 35 \
    --max-total-amount 35 \
    --ttl 30m \
    --assets USDC \
    --use-card \
    --output json

Budget rule

The issuer does not partially approve card authorizations. The scoped card amount must cover the merchant's final charge, including tax, shipping, tips, and exchange-rate movement when relevant.

Card lifecycle

Status	Meaning
Pending	Passport is waiting for card issuance, issuer status, or webhook projection.
Active	The card is issued and can be used before expiry, subject to its remaining budget and issuer authorization rules.
Completed	The card's approved budget is exhausted and it cannot be used for new purchases. Refunds, reversals, and chargebacks can still appear as activity.
Expired	The card expiry has passed before use or before a usable authorization.
Failed	Card issuance failed or the issuer rejected the card create request. Retry only after the underlying cause is clear.
Locked or canceled	The issuer or Passport has disabled the card. A canceled card cannot be used for new purchases.

The Cards page intentionally shows masked metadata: last four digits, budget, available amount, expiry, session id, status, and activity. PAN and CVC should only be handled inside the approved card-execution boundary.

Security boundaries

Operation	Authorization boundary
Application and KYC	User-driven flow on the Cards page and hosted KYC page.
Manual card actions	User action in Passport, with passkey step-up where required.
Agent card issuance	Approved agent session delegation and card execution constraints. The autonomous agent does not perform passkey step-up at payment time.
Card secret use	Approved checkout execution path only. Do not expose PAN or CVC in dashboard UI, logs, analytics, or agent transcripts.

Troubleshooting

Symptom	Likely cause and action
KYC link says applicant not found	The browser may have stale issuer session state. Open the exact KYC link in a private browser window. If it still fails, refresh the application from the Cards page and confirm the issuer profile id.
No reserve row appears	Issuer configuration may include unsupported chains or tokens. Passport should only show rows from the configured chain/token whitelist.
Card create fails	Check KYC status, reserve funding, expiry, active card limits, daily create limits, and scoped card amount.
Authorization declines	The merchant charge may exceed the card ceiling, the card may be expired, or the card issuer may decline based on card or risk rules.
Card still looks active after use	Refresh Cards after issuer settlement webhooks land. A card should stay active while approved budget remains and move to `completed` only when that budget is exhausted.