Save a Card

Introduction

The user enters their card into a Crossmint-hosted UI, and your app receives a paymentMethodId for subsequent API calls. Raw card data never reaches your servers. Saving the card does not grant spending permission. You register the saved card to discover its supported rails, then create and verify a separate order intent before minting credentials.

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 — authenticate the user with Crossmint Auth or a configured external provider.

Saved card limit. In production, each project has a limit on the number of cards it can save, unless the Crossmint team has raised or removed it for the project. 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.

Steps

Install the SDK

npm install @crossmint/client-sdk-react-ui

yarn add @crossmint/client-sdk-react-ui

pnpm add @crossmint/client-sdk-react-ui

bun add @crossmint/client-sdk-react-ui

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>
    );
}

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>
    );
}

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

Continue to Register a Card to discover which order-intent rails support the saved card.

Introduction

Agent Cards

Agent Wallets

Agent Checkouts

API Reference

Introduction

Prerequisites

Steps

Next Steps

​Introduction

​Prerequisites

​Steps

​Next Steps

Introduction

Prerequisites

Steps

Next Steps