Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Introduction

Retrieving secure card numbers is the final step in the cards flow. Once an order intent is active, you exchange the orderIntentId and a merchant descriptor for a secure one-time card number, expiration, and CVC that the agent uses to complete the purchase. Credentials are scoped to the merchant you specify, so they can only be used where the user authorized the spending. The agent never sees the real card number.

​
Prerequisites

  • An order intent with phase: "active". See Give Card Permission if you have not done this yet.
  • The orderIntentId of the active order intent.
  • An authenticated user with a JWT.

​
Fetch Credentials

Send a POST request to /api/unstable/order-intents/{orderIntentId}/credentials with the merchant information. The merchant details are required so that Crossmint can generate credentials scoped to that specific merchant. 
const BASE_URL = "https://staging.crossmint.com/api/unstable";

const response = await fetch(
    `${BASE_URL}/order-intents/${orderIntentId}/credentials`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "X-API-KEY": CROSSMINT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
        body: JSON.stringify({
            merchant: {
                name: "Whole Foods",
                url: "https://www.wholefoodsmarket.com",
                countryCode: "US",
            },
        }),
    }
);

const credentials = await response.json();
The response contains the secure card number details your agent needs to complete a purchase: 
{
    "card": {
        "number": "4000056655665556",
        "expirationMonth": "12",
        "expirationYear": "2027",
        "cvc": "123"
    },
    "expiresAt": "2026-05-01T00:00:00Z"
}

​
Merchant Fields

FieldDescription
nameDisplay name of the merchant
urlThe merchant’s website URL
countryCodeTwo-letter ISO country code (for example US, GB, DE)
The merchant descriptor must be passed on every credential fetch — it is not stored on the order intent. For recurring spend at a fixed merchant, persist these fields alongside the orderIntentId when you set up the card permission. See What to persist on the Give Card Permission page for the full guidance.

​
List Card Permissions

To see all card permissions (order intents) for the authenticated user, send a GET request to the order intents endpoint: 
const BASE_URL = "https://staging.crossmint.com/api/unstable";

const response = await fetch(`${BASE_URL}/order-intents`, {
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": CROSSMINT_API_KEY,
        Authorization: `Bearer ${jwt}`,
    },
});

const orderIntents = await response.json();
// Returns an array of order intents with their phases and spending rules
Only order intents with phase: "active" can have their credentials fetched. Expired order intents return an error. For the full credentials API schema, see the Get Order Intent Credentials API Reference.

​
Common Gotchas

The merchant field is required on every credential request. A card number fetched for one merchant will not authorize at another — if the agent needs to spend at a different merchant, create a new card permission.
Even within an active order intent, the returned card data is short-lived. Fetch credentials as close to the purchase as possible rather than caching them.
If the user has not yet completed the passkey authorization, wait for onVerificationComplete before calling this endpoint.

​
Next Steps

Remove Cards

Remove saved cards, delete agents, or rotate a card permission.

Cards Quickstart

Revisit how credential retrieval fits into the full cards flow.