Retrieve Secure Card Numbers

Mint a one-time card-network credential or an encrypted saved card from an active order-intent rail

Mint a credential for a specific amount and merchant from an order intent. Choose one rail from the order-intent response and use that same rail for verification and credential minting.

The request and response shape depend on the rail:

Rail	What you receive	When it appears
agentic-token	A one-time card number or network token issued by Visa Intelligent Commerce or Mastercard Agent Pay, bounded by the requested amount and merchant	The saved card supports a card-network rail
encrypted-card	The user’s saved card, encrypted to an RSA public key that you provide. Minting consumes the requested amount from the order intent, like the other rails	No card-network rail is usable for the order intent. In production, only for projects with encrypted card access enabled

Prerequisites

• Verified order intent — follow Create an Agent Card and wait for a rail with status: "active".
• Crossmint API key — a client-side key with the order-intents.read and order-intents.credentials scopes. To recover from ORDER_INTENT_CVC_RECOLLECTION_REQUIRED with the hosted CVC step, the same key also needs payment-methods.read and payment-methods.update. In staging, all scopes are included by default.
• User JWT — use the JWT for the user who owns the order intent.

Mint a Card-Network Credential

Find the agentic-token rail you want to use and confirm that it is active and supports card credentials. Other rails can remain pending. Send the selected rail’s rail and provider values back in the request.

This example continues from the merchant-scoped order intent created in the previous guide, so the credential request does not repeat the merchant:

const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";
const orderIntentId = "a1b2c3d4-e5f6-4890-abcd-ef1234567890";

const orderIntentResponse = await fetch(
    `https://staging.crossmint.com/api/unstable/order-intents/${orderIntentId}`,
    {
        headers: {
            "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
    }
);

if (!orderIntentResponse.ok) {
    throw new Error(`Order intent retrieval failed (${orderIntentResponse.status})`);
}

const orderIntent = await orderIntentResponse.json();

const selectedRail = orderIntent.rails.find(
    (rail) =>
        rail.rail === "agentic-token" &&
        rail.status === "active" &&
        rail.credentialFormats.includes("card")
);

if (selectedRail == null) {
    throw new Error("No active card-network rail supports card credentials");
}

const response = await fetch(
    `https://staging.crossmint.com/api/unstable/order-intents/${orderIntent.orderIntentId}/credentials`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
        body: JSON.stringify({
            rail: selectedRail.rail,
            provider: selectedRail.provider,
            amount: { value: "25.00", currency: orderIntent.amount.currency },
            credential: { format: "card" },
        }),
    }
);

if (!response.ok) {
    throw new Error(`Credential creation failed (${response.status})`);
}

const result = await response.json();

Open Order Intents

If orderIntent.merchant is absent, include a merchant in every credential request:

merchant: {
    name: "Acme Store",
    url: "https://acme.example.com",
    countryCode: "US",
},

The response returns the selected rail and the credential value. An inactive status on another rail does not affect this request:

{
    "id": "cred_123",
    "rail": "agentic-token",
    "provider": "vic",
    "amount": { "value": "25.00", "currency": "USD" },
    "credential": {
        "format": "card",
        "value": {
            "number": "4000001000004242",
            "expirationMonth": 12,
            "expirationYear": 2030,
            "cvc": "123"
        }
    },
    "expiresAt": "2099-01-01T00:05:00.000Z"
}

Treat the credential as a secret. Use it immediately, never log it, and do not persist it for later reuse. Minting deducts the requested amount from the order intent even if the credential is never used.

For the complete schema, see the Create Order Intent Credential API Reference.

Mint an Encrypted Card

When the order intent’s rails array contains an encrypted-card entry, the response cannot contain a network-issued one-time card. Instead, the user’s saved card is encrypted inside the PCI-compliant vault to a public key that you control, and Crossmint returns the ciphertext. Only the holder of the matching private key can read the card.

Generate a Key Pair

Generate an RSA key pair of at least 2048 bits for the RSA-OAEP-256 algorithm. Keep the private key wherever the agent will decrypt the card; only the public key is sent to Crossmint.

const { publicKey, privateKey } = await crypto.subtle.generateKey(
    {
        name: "RSA-OAEP",
        modulusLength: 2048,
        publicExponent: new Uint8Array([1, 0, 1]),
        hash: "SHA-256",
    },
    true,
    ["encrypt", "decrypt"]
);

const { kty, n, e } = await crypto.subtle.exportKey("jwk", publicKey);

Request the Encrypted Card

Send the public key as a JWK with only the kty, n, and e members. The request takes the same amount and optional merchant as the other rails; the encrypted-card rail has no provider:

const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";
const orderIntentId = "a1b2c3d4-e5f6-4890-abcd-ef1234567890";

const response = await fetch(
    `https://staging.crossmint.com/api/unstable/order-intents/${orderIntentId}/credentials`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
        body: JSON.stringify({
            rail: "encrypted-card",
            amount: { value: "25.00", currency: "USD" }, // the order intent's currency
            credential: {
                format: "card",
                publicKey: { kty, n, e },
            },
        }),
    }
);

if (!response.ok) {
    throw new Error(`Credential creation failed (${response.status})`);
}

const result = await response.json();

The response contains the encrypted card as a compact JWE string, with the same id, amount, and expiresAt fields as a card-network credential. The id is issued by Crossmint. expiresAt is the earlier of two deadlines: the end of the window in which the vault still holds the card’s security code, and the order intent’s own expiresAt. After it passes, mint again for what you still need; the amount already minted does not come back. If the security-code window is what ended, the rail reads pending_cvc_recollection and the user re-enters the CVC first; if the order intent itself expired, create a new one:

{
    "id": "6f1c2a8e-3b7d-4c1e-9a2f-0d5e7b9c4a11",
    "rail": "encrypted-card",
    "amount": { "value": "25.00", "currency": "USD" },
    "credential": {
        "format": "card",
        "value": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwidHlwIjoiSldFIn0..."
    },
    "expiresAt": "2026-09-23T16:20:00.000Z"
}

Decrypt the Card

The JWE uses RSA-OAEP-256 for key encryption and A256GCM for content encryption. Decrypt it with your private key using a JOSE library. The plaintext is a JSON object with the same fields as a card-network credential:

import { compactDecrypt } from "jose";

const { plaintext } = await compactDecrypt(result.credential.value, privateKey);
const card = JSON.parse(new TextDecoder().decode(plaintext));
// { number: "4242424242424242", expirationMonth: 12, expirationYear: 2030, cvc: "123" }

The decrypted value is the user’s real card, not a one-time number. Treat it with the same care as raw cardholder data: decrypt it only where the payment is made, never log or persist it, and discard the private key when the purchase completes. Minting consumes the requested amount from the order intent even if the card is never charged, and the order intent refuses a mint above amount.available. The card network does not enforce the allowance, so your agent must keep each purchase within the amount it minted and the order intent’s merchant.

Encrypted Card Errors

Error code	Meaning
ORDER_INTENT_INVALID_PUBLIC_KEY	The vault rejected publicKey, for example because n and e do not form a usable RSA key
ADDON_REQUIRED	Encrypted card access is not enabled for the project in production; contact us for access
ORDER_INTENT_CVC_RECOLLECTION_REQUIRED	The card security code (CVC) has expired or is no longer available for this card. The encrypted-card rail shows status: "pending_cvc_recollection". Ask the user to re-enter the CVC with Recollect the CVC, then retry the request
ORDER_INTENT_CREDENTIAL_UNAVAILABLE	The vault rejected the saved card, or the request does not fit the order intent: a different currency, no merchant on an order intent created without one, or a merchant other than the one the order intent was created with. The message says which. A request may name only part of the merchant; every field it names must match
ORDER_INTENT_AMOUNT_EXCEEDED	The requested amount is above amount.available
ORDER_INTENT_CREDENTIAL_ALREADY_ISSUED	409. A credential was already issued for this Idempotency-Key. Credential payloads are returned once; use a new key for a new mint
ORDER_INTENT_EXPIRED	The order intent has passed its expiresAt
ORDER_INTENT_CANCELLED	The order intent was cancelled

To make a retry safe, send an Idempotency-Key header (1 to 255 characters) with the request. A second call with the same key never consumes the amount again: while the first is unanswered it is refused, and after a successful mint it returns ORDER_INTENT_CREDENTIAL_ALREADY_ISSUED. Without the header every call is a new mint.

A malformed request, such as a publicKey whose kty is not RSA or whose encoded n is shorter than 342 base64url characters, fails schema validation before the vault is called and returns a 400 without an order-intent error code. Other unusable RSA keys can reach the vault and return ORDER_INTENT_INVALID_PUBLIC_KEY.

List Order Intents

List every order intent owned by the authenticated user:

const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";

const response = await fetch("https://staging.crossmint.com/api/unstable/order-intents", {
    headers: {
        "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
        Authorization: `Bearer ${jwt}`,
    },
});

if (!response.ok) {
    throw new Error(`Order intent listing failed (${response.status})`);
}

const orderIntents = await response.json();

Each item includes its live balance and rails. Use GET /api/unstable/order-intents/{orderIntentId} when you only need to refresh one order intent.

Common Gotchas

The request amount must fit the available balance

Use the same currency as the order intent and keep the requested value at or below amount.available.

Creating a credential spends allowance capacity

Do not retry a credential request blindly. Each successful mint is a new credential and consumes the requested amount.

A pending rail cannot mint credentials

Complete allowance verification for the rail you selected and fetch the order intent again before minting. You do not need to verify unrelated rails.

Open order intents require a merchant

If the order intent was created without merchant, include one in every credential request. If the merchant was set at creation, omit it when minting, or repeat it exactly: a different merchant is refused. This applies to every rail, encrypted-card included.

Encrypted cards differ only in the credential block

With rail: "encrypted-card", send amount, an optional merchant, and credential.format with credential.publicKey. Do not send provider. Requests with unknown fields are rejected.

Next Steps

Cancel Card Access

Cancel an order intent or delete a saved card

Cards Quickstart

Run the complete flow in the reference app