Approve an Order Intent

An order intent gives an agent a limited amount to spend before a fixed expiration. The agent can pay several times with one order intent, until it spends the amount or the order intent expires. Each payment gets a new credential. One order intent can have several rails, and each rail has its own status, credential formats, and verification.

Prerequisites

Registered card — register a saved card. A card with an enabled rail unlocks card-network credentials; a card without one can still use the encrypted card fallback described below.
Encrypted card access (only for your own checkout) — with Agent Checkouts, you do not need it. To get the encrypted card in your own checkout in production, contact us for access. Staging projects have it.
Crossmint API key — a client-side key with order-intents.create and order-intents.read scopes. In staging, all scopes are included by default.
User JWT — use the JWT for the user who owns the saved card.

Create the Order Intent

Create an order intent with the saved card, spending limit, description, expiration, and merchant. Include the merchant now when you already know where the agent will spend:

const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";
const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString();

const response = await fetch("https://staging.crossmint.com/api/unstable/order-intents", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
        Authorization: `Bearer ${jwt}`,
    },
    body: JSON.stringify({
        paymentMethodId: "pm_123",
        amount: { value: "150.00", currency: "USD" },
        merchant: {
            name: "Acme Store",
            url: "https://acme.example.com",
            countryCode: "US",
        },
        description: "Weekly grocery purchases",
        expiresAt,
    }),
});

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

const orderIntent = await response.json();

The response separates the order intent’s lifecycle from the status of each rail:

{
    "orderIntentId": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "paymentMethodId": "pm_123",
    "status": "active",
    "amount": {
        "total": "150.00",
        "spent": "0.00",
        "reserved": "0.00",
        "available": "150.00",
        "currency": "USD"
    },
    "merchant": {
        "name": "Acme Store",
        "url": "https://acme.example.com",
        "countryCode": "US"
    },
    "description": "Weekly grocery purchases",
    "rails": [
        {
            "rail": "agentic-token",
            "provider": "vic",
            "status": "pending_verification",
            "credentialFormats": ["card", "network-token"]
        }
    ],
    "verificationConfig": {
        "environment": "test",
        "publicApiKey": "key_test_123",
        "allowanceId": "alw_123"
    },
    "expiresAt": "2099-01-01T00:00:00.000Z"
}

Setting merchant when creating the order intent is preferred when you know it. The merchant is fixed for the lifetime of that order intent, and credential requests inherit the restriction. If the agent will choose a merchant later, omit merchant. This creates an open order intent, and every credential request must supply the merchant instead. The top-level status is active while the allowance exists. A specific rail can still require verification. Treat rails as a set of independent ways to spend the same allowance:

Choose the rail that provides the credential you need.
If that rail is pending_verification, verify it.
Once it is active, mint with the same rail and provider values.

You do not need every rail to be active. Other rails can remain pending_verification or error without blocking the selected rail. For example, when an allowance contains both VIC and SPT, minting a VIC credential only requires the VIC rail to be verified; you do not need to complete an SPT step. The card network rails are Visa Intelligent Commerce and Mastercard Agent Pay. The same selection rule applies to every rail.

Encrypted Card Fallback

When no card network rail can give a credential, an active order intent adds an encrypted-card rail to rails. Failed card network rails stay in the array, with their error. Select the entry whose rail is encrypted-card; do not assume a one-element array:

{
    "rails": [
        {
            "rail": "agentic-token",
            "provider": "vic",
            "status": "error",
            "credentialFormats": [],
            "error": { "code": "CARD_REJECTED" }
        },
        {
            "rail": "encrypted-card",
            "status": "active",
            "credentialFormats": ["card"]
        }
    ]
}

The encrypted-card rail has no provider, and it never needs verification. Skip the OrderIntentVerification step for it.

With Agent Checkouts, the encrypted card works with no setup. The card stays inside the Crossmint vault. Your reads of the order intent can omit the rail; the checkout uses it anyway. See Use With Agent Checkouts.
With your own checkout, your app gets the user’s real card, encrypted to your RSA public key. In production, this needs encrypted card access for your project (contact us). Without it, the rail is not in rails, and a direct request fails with ADDON_REQUIRED. See Get a Card Number.

When a card network rail becomes available, prefer it: the card network enforces the limit, and the real card number is never exposed. See Card Rails and PCI Compliance.

Verify the Selected Rail

When the rail you want to use has status: "pending_verification", render OrderIntentVerification in your client application. Do not start verification merely because an unrelated rail is pending.

import {
    OrderIntentVerification,
    type OrderIntentVerificationProps,
} from "@crossmint/client-sdk-react-ui";

function VerifyOrderIntent({
    orderIntent,
}: {
    orderIntent: OrderIntentVerificationProps["orderIntent"];
}) {
    return (
        <OrderIntentVerification
            orderIntent={orderIntent}
            displayName="Acme Shopping Agent"
            onVerificationComplete={() => {
                console.log("Allowance verified");
            }}
            onVerificationError={(error) => {
                console.error("Allowance verification failed", error);
            }}
        />
    );
}

After verification completes, fetch the order intent again and wait for the selected rail to report status: "active". You do not need to wait for the other rails. Card registration never prompts for verification. Verification belongs to an individual order-intent rail. The first Visa verification on a device can create a passkey; later order intents authenticate with the existing passkey when the device remains bound. The component also handles the Mastercard-hosted flow. For the complete request and response schemas, see the Create Order Intent API Reference.

Use With Agent Checkouts

When a checkout asks for payment, create the order intent for the amount and merchant of the payment request, and send its ID. See Pay for a Checkout. Agent Checkouts can use the encrypted-card rail without encrypted card access. The access protects the card number from your systems. Inside an agent checkout, the card never leaves the Crossmint vault: the checkout enters it at the merchant, and your app handles only the orderIntentId. Your own reads of the order intent can omit the rail, but the checkout uses it while the saved card’s CVC is available. If the checkout answers rail_unavailable, ask for the CVC again.

Common Gotchas

An active order intent can still have a pending rail

Read rails[].status before minting. The top-level status describes the order intent’s lifetime, not whether every rail is ready.

Each order intent has its own verification state

Register the card once, then verify only the order-intent rail you plan to use when it returns pending_verification. Do not repeat card registration to authorize a new allowance.

The encrypted-card rail does not enforce the allowance

Card networks enforce amount and merchant only for agentic-token rails. When your agent spends with an encrypted card, keep the purchase within the order intent’s limits yourself and cancel the order intent when it is no longer needed.

The expiration is required

Set expiresAt to a future ISO 8601 timestamp that matches the permission you present to the user.

A scoped merchant cannot be changed later

Include merchant when creating the order intent if you already know it. Otherwise, omit it and supply a merchant with every credential request.

Next Steps

Pay for a Checkout

Pay with the order intent in an agent checkout

Get a Card Number

Get a credential for your own checkout

Create an Order Intent

Review the complete create request schema

Introduction

Agent Cards

Agent Wallets and Onramps

Agent Checkouts

API Reference

Prerequisites

Create the Order Intent

Encrypted Card Fallback

Verify the Selected Rail

Use With Agent Checkouts

Common Gotchas

Next Steps

Pay for a Checkout

Get a Card Number

Create an Order Intent

​Prerequisites

​Create the Order Intent

​Encrypted Card Fallback

​Verify the Selected Rail

​Use With Agent Checkouts

​Common Gotchas

​Next Steps

Pay for a Checkout

Get a Card Number

Create an Order Intent

Prerequisites

Create the Order Intent

Encrypted Card Fallback

Verify the Selected Rail

Use With Agent Checkouts

Common Gotchas

Next Steps