Agent Cards Quickstart ⚡

Run the reference app in staging: sign in, save a card, approve an order intent, and get a card number

This quickstart runs the Agent Cards reference app in staging. At the end, a user can sign in, save a card, register its rails, approve an order intent, and get a secure card number.

To buy with the card through Agent Checkouts, which uses production keys, use the prompt in the Agent Checkouts Quickstart instead.

Try the live demo

See the full flow without setting anything up locally

View the reference app

The full reference code for saved cards and order intents

Prerequisites

• Node.js and pnpm — Node.js 20 or later.
• Stytch account — a Stytch account. The example uses Stytch to sign in users. Any supported auth provider works in your own app.

Eligible Cards

Agent Cards works with any credit or debit card. What varies by card is who issues the agent’s credential: a card-network program, or Crossmint’s encrypted card fallback.

Card-network rails — Visa Intelligent Commerce and Mastercard Agent Pay — support a subset of cards, and Visa and Mastercard keep expanding that coverage:

• Mastercard Agent Pay: Mastercard credit and debit cards
• Visa Intelligent Commerce: U.S.-issued Visa credit and debit cards, except business cards, prepaid cards, Chase cards, and Fidelity cards

Cards that no card-network rail supports yet, such as AMEX, Ramp, or non-US Visa cards, use the encrypted card rail. With Agent Checkouts, these cards work with no setup. To get the encrypted card in your own checkout in production, contact us.

Run the App

1. Clone the repository and install dependencies

   git clone https://github.com/Crossmint/card-permissions-quickstart.git
   cd card-permissions-quickstart
   pnpm install
   cp .env.example .env.local
   

   You can ask your coding agent to do these steps for you.

2. Get a Crossmint staging client key

   Sign in to the Crossmint Staging Console, create a project, and create a client-side API key. In staging, all scopes are included by default.

   Your AI assistant can also do this step with the Crossmint MCP server: in staging, create a project and a web client key for http://localhost:3000 with the payment-methods.* and order-intents.* scopes.

   Paste the key into .env.local:

   .env.local

   NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY=YOUR_CROSSMINT_CLIENT_API_KEY
   
3. Set up Stytch

   In the Stytch dashboard, in the Test environment of a B2C project:

   1. In Configuration → SDK Configuration → OAuth, enable Google. The shared Stytch test client works, with no Google Cloud setup.
   2. In Configuration → Redirect URLs, add http://localhost:3000 as both Login and Signup. Use exactly that value, with no trailing slash and no /callback.
   3. In Project Settings → API Keys, copy the Public token (public-token-test-...) into .env.local:

   .env.local

   NEXT_PUBLIC_STYTCH_PUBLIC_TOKEN=YOUR_STYTCH_PUBLIC_TOKEN
   
4. Register Stytch as your auth provider in Crossmint

   In the Crossmint Staging Console, under 3P Auth providers:

   1. Select Stytch in the provider list.
   2. Paste your Stytch Project ID (project-test-...). Stytch shows it in Project Settings → Project ID.
   3. Keep Verifier Id as sub, the default.

   Crossmint then accepts the JWTs that your Stytch project signs.

5. Run the dev server

   pnpm dev
   

   Open http://localhost:3000.

Understand the User Flow

The app takes the user through six steps:

1. Sign in. The user signs in with Google through Stytch. The app passes the Stytch JWT to the Crossmint SDK, so that every API call belongs to that user.
2. Save a card. The CrossmintPaymentMethodManagement component collects the card in a PCI-compliant form and returns a paymentMethodId.
3. Register the card. Registration finds the card’s rails, such as Visa Intelligent Commerce or Mastercard Agent Pay. It gives no spending permission and needs no verification.
4. Create an order intent. The app creates an order intent with an amount, a description, an expiration, and, when known, the merchant. The response can have several rails, each with its own status. If no card network rail can be used, the response also has an encrypted-card rail. In production, the app gets the encrypted card only when the project has encrypted card access.
5. Verify the rail that you use. If that rail has status: "pending_verification", the OrderIntentVerification component runs the card network’s step. Other rails can stay pending. A returning Visa user approves with the passkey that is already on the device.
6. Get a card number. The app asks for a credential for a specific amount, with the rail’s rail and provider. If the order intent has no merchant, the app gives the merchant now. The response has a one-time card number, an expiration date, and a CVC. For the encrypted-card rail, the app sends an RSA public key and gets the saved card as a JWE to decrypt.

Treat rails as a menu, not a checklist. Only the rail that you use must be active. Other rails do not block it.

Launching in Production

1. Create a production project and a production client key in the Crossmint Console, with the payment-methods.* and order-intents.* scopes.
2. Register your auth provider in the production project, under 3P Auth providers, and add your app’s origins to the key.
3. Replace the staging key in your app with the production key.
4. Test with real cards: a production project can save up to 50 cards. Before you launch to your users, contact the Crossmint team to enable your project fully.
5. To buy on any website with the saved card, add Agent Checkouts. See the Agent Checkouts Quickstart.

Learn More

Card Rails and PCI

The rails, the card data path, and your PCI scope

Customize UI

Style the approval and the CVC form to match your brand