Recollect the CVC

The encrypted-card rail returns the user’s saved card, including the CVC encrypted when the card was saved. Crossmint keeps that CVC for a limited time. Once it expires, the rail stops minting until the user types the CVC again. CrossmintCvcRecollection from @crossmint/client-sdk-react-ui renders Crossmint’s hosted CVC field for that step: the digits never reach your application.

Prerequisites

Saved and registered card — follow Save a Card and Register a Card.
Order intent with an encrypted-card rail — follow Create an Agent Card.
Crossmint API key — a client-side key with the order-intents.read, payment-methods.read, and payment-methods.update scopes. In staging, all scopes are included by default.
User JWT — the JWT for the user who owns the card.
React SDK — @crossmint/client-sdk-react-ui 4.7.0 or later, with CrossmintProvider configured as in the other card guides.

When to Render the Component

Two signals tell you that the CVC must be collected again. Handle both.

Signal	Where it appears	Meaning
`status: "pending_cvc_recollection"`	The `encrypted-card` entry in `rails` of `GET /api/unstable/order-intents/{orderIntentId}`	The saved CVC expired. The rail cannot mint until the user re-enters it
`409` with `code: "ORDER_INTENT_CVC_RECOLLECTION_REQUIRED"`	`POST /api/unstable/order-intents/{orderIntentId}/credentials` with `rail: "encrypted-card"`	The CVC expired between your last read and the mint, or is no longer available

A rail read as active can still answer 409 if the CVC expires before the mint. Read the order intent right before the user starts the mint flow, and treat the 409 as the same condition as the pending status.

const encryptedCard = orderIntent.rails.find((rail) => rail.rail === "encrypted-card");
const needsCvc = encryptedCard?.status === "pending_cvc_recollection";

Render the Hosted CVC Field

Render CrossmintCvcRecollection in your client application with the user’s JWT and the paymentMethodId of the order intent’s card. The component renders a single CVC input and a confirm button, and no explanation of its own, so tell the user why the code is requested again.

import { CrossmintCvcRecollection } from "@crossmint/client-sdk-react-ui";

function RecollectCvc({ jwt, paymentMethodId }: { jwt: string; paymentMethodId: string }) {
    return (
        <div>
            <p>The security code for this card has expired. Enter it again to continue.</p>
            <CrossmintCvcRecollection
                jwt={jwt}
                paymentMethodId={paymentMethodId}
                onComplete={() => {
                    console.log("CVC updated");
                }}
                onError={(error) => {
                    console.error("CVC recollection failed", error);
                }}
            />
        </div>
    );
}

After onComplete fires, fetch the order intent again: the encrypted-card rail returns to status: "active" and you can mint as described in Retrieve Secure Card Numbers. onError receives { reason, retriable, message }. When retriable is true, the form stays mounted and the user can submit again. When it is false, the component renders nothing afterwards, so unmount it and show your own message. To style the form, pass an appearance prop as described in Customize UI.

Test in Staging

A freshly saved card does not reach pending_cvc_recollection during a normal test run. In staging, expire the CVC on demand:

cURL

curl --request POST \
    --url https://staging.crossmint.com/api/unstable/cvc-recollection/expire \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: <YOUR_CROSSMINT_CLIENT_API_KEY>' \
    --header 'Authorization: Bearer <YOUR_USER_JWT>' \
    --data '{ "paymentMethodId": "<PAYMENT_METHOD_ID>" }'

The call answers 204. The rail then reports pending_cvc_recollection and mints answer 409 until the user completes the form. The endpoint is staging-only.

Introduction

Agent Cards

Agent Wallets

Agent Checkouts

API Reference

Prerequisites

When to Render the Component

Render the Hosted CVC Field

Test in Staging

Next Steps

Retrieve Secure Card Numbers

Cancel Card Access

​Prerequisites

​When to Render the Component

​Render the Hosted CVC Field

​Test in Staging

​Next Steps

Retrieve Secure Card Numbers

Cancel Card Access

Prerequisites

When to Render the Component

Render the Hosted CVC Field

Test in Staging

Next Steps