Save a Card

Save a user’s card in a Crossmint card form inside your app

The user enters the card in a Crossmint card form inside your app, and your app gets a paymentMethodId. Card data never reaches your servers.

Saving the card gives no spending permission. The agent pays only within an order intent that the user approves, and one order intent can cover several payments. See Approve an Order Intent.

Prerequisites

• Crossmint API key — a client-side key with the payment-methods.create, payment-methods.read, and payment-methods.update scopes. The update scope lets the user re-enter the card security code (CVC) later, when a card credential needs it. In staging, all scopes are included by default.
• User JWT — sign in the user with your auth provider, registered under 3P Auth providers in the Crossmint Console. See Bring Your Own Auth.

Saved card limit. In production, a project can save up to 50 cards without contacting Crossmint. To save more, contact our sales team. The first 1,000 saved cards are free, and after that each saved card costs 0.05 USD. The limit counts the saved cards of all the project’s users; deleted cards do not count. Staging has no limit. The limit applies to cards only: bank accounts have no limit, but in production saving them must be enabled for your project.

At the limit, saving another card returns 400 with the code payments:payment-method.card-limit-reached, and the project’s limit in parameters.limit. Cards that are already saved keep working, so agents can still spend with them. To save a new card, remove a card that a user no longer needs. To raise the limit, contact the Crossmint team.

Save the Card

1. Install the SDK

   npm

   npm install @crossmint/client-sdk-react-ui
   
2. Wrap your app with the Crossmint provider

   Set up CrossmintProvider at the root of your app. This makes the Crossmint SDK available to all child components.

   "use client";
   import { CrossmintProvider } from "@crossmint/client-sdk-react-ui";
   
   function App() {
       return (
           <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY}>
               {/* Your app */}
           </CrossmintProvider>
       );
   }
   
3. Add the card collection component

   Place this component on a page where the user manages their payment methods, or in an ephemeral UI dedicated to saving cards.

   The CrossmintPaymentMethodManagement component handles all PCI compliance concerns. Card data is collected directly by Crossmint and never passes through your servers — this is why the UI must be rendered inside your app rather than called from your backend.

   In staging, use the test card number 4242 4242 4242 4242 with any future expiration date and any three-digit CVC. For additional scenarios, see Test Agent Cards.

   import { CrossmintPaymentMethodManagement } from "@crossmint/client-sdk-react-ui";
   
   function PaymentMethodsPage({ jwt }: { jwt: string }) {
       // jwt comes from your own auth provider (for example Stytch, Auth0, Dynamic)
   
       const handlePaymentMethodSelected = (paymentMethod: { paymentMethodId: string }) => {
           // Persist this ID so you can register the card and create order intents.
           console.log("Card saved:", paymentMethod.paymentMethodId);
       };
   
       return (
           <div>
               <h2>Payment Methods</h2>
               <p>Save a card so your agent can request payments on your behalf.</p>
               <CrossmintPaymentMethodManagement
                   jwt={jwt}
                   onPaymentMethodSelected={handlePaymentMethodSelected}
               />
           </div>
       );
   }
   
4. Store the payment method ID

   When the user saves a card, the onPaymentMethodSelected callback returns a paymentMethodId. Persist this ID in your backend associated with the user, apply strict access controls, and avoid exposing it in client-side storage or logs.

   The ID cannot reveal the original card number, but it can be used to register the card and create order intents.

Next Steps

Register a Card

Find the rails that the saved card supports

Approve an Order Intent

Let the user approve a limit on the card

Create a Payment Method

Review the saved card object