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	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 order-intents.read and order-intents.credentials scopes. 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 encrypted-card rail has no provider, and the request takes no amount or merchant:

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",
            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:

{
    "rail": "encrypted-card",
    "credential": {
        "format": "card",
        "value": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwidHlwIjoiSldFIn0..."
    }
}

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. Crossmint does not deduct from the order intent balance for encrypted-card credentials, and the card network does not enforce the allowance, so your agent must keep purchases within the order intent’s amount and 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_CREDENTIAL_UNAVAILABLE	The saved card cannot be encrypted, for example because its CVC was not captured when it was saved
ORDER_INTENT_EXPIRED	The order intent has passed its expiresAt
ORDER_INTENT_CANCELLED	The order intent was cancelled

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. This applies only to agentic-token rails; the encrypted-card request takes no merchant.

Encrypted cards use a different request shape

Do not send provider, amount, or merchant with rail: "encrypted-card". Send only credential.format and credential.publicKey. 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