Skip to main content

Introduction

Saving a card enables a physical card to be tokenized for agentic use and onramps. The user enters their card into a Crossmint-hosted UI, Crossmint tokenizes it in a PCI-compliant vault, and your app receives a paymentMethodId it can use in later flows to retrieve card details. Raw card data never reaches your servers. Think of this like Apple Pay or a browser storing a card once so it can be used securely later — but with one important difference. Saving a card does not authorize agents to use it. Enrollment is a separate, explicit step covered in the next guide.

Prerequisites

  • A registered agent with a valid agentId. See Register an Agent if you have not done this yet.
  • The user must be authenticated and you must have a JWT for them.

Steps

1

Install the SDK

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.
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 Testing All Flows.
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 initiate payment-related operations, including verification and agent card setup.

Testing All Flows

In staging, the test card number determines how downstream flows behave — success, card-not-eligible, issuer decline, OTP challenges, and so on. Use these cards to exercise every branch of your integration without needing live cards or real issuers.

Visa

Use any future expiration date and any three-digit CVC.

What Is Next

The paymentMethodId represents a saved card, but not yet a card that an agent can use. Before giving any agent cards, verify the card for agentic payments. Continue to Verify a Card to authorize this saved card for agent use through a one-time passkey verification step.