Skip to main content

​
Introduction

A card permission is created as an order intent — a request granting an agent scoped access to a card, defined by one or more spending rules (amount, description, frequency, and more). The user authorizes the intent with their passkey, after which the permission becomes active and secure card numbers can be retrieved by the agent.

​
Prerequisites

  • A saved card that has been verified for agentic payments. See Save a Card and Verify a Card if you have not done this yet.
  • The agentId from Register an Agent.
  • The paymentMethodId of the verified card.
  • An authenticated user with a JWT.
Eligible CardsYou can currently use card permissions with Mastercard and eligible U.S.-issued Visa credit and debit cards.Not supported for Visa: non-US cards, business cards, prepaid cards, Chase cards, Fidelity cards.For AMEX and Ramp cards, contact us.

​
Steps

1

Create the order intent

Send a POST request to /api/unstable/order-intents with the agent, the card to charge, and one or more spending rules.
const BASE_URL = "https://staging.crossmint.com/api/unstable";

const response = await fetch(`${BASE_URL}/order-intents`, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
        Authorization: `Bearer ${jwt}`,
    },
    body: JSON.stringify({
        agentId: agentId,
        payment: { paymentMethodId: paymentMethodId },
        mandates: [
            {
                type: "maxAmount",
                value: "150.00",
                details: { currency: "usd", period: "monthly" },
            },
            {
                type: "description",
                value: "Weekly grocery purchases",
            },
        ],
        expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(), // 1 year from now
    }),
});

const orderIntent = await response.json();
console.log(orderIntent.orderIntentId);
console.log(orderIntent.phase);
// "requires-verification" or "active"
A card permission has two time controls. The mandate period (weekly, monthly, yearly) determines how often the spending limit resets. The expiresAt field determines when the permission itself stops working — after this date, the agent can no longer use it regardless of remaining balance. If expiresAt is not provided, it defaults to seven days from creation. Set expiresAt to a date that matches your use case — for example, a monthly spending limit typically needs an expiry at least one month in the future.For the full list of supported spending rule types and their fields, see the Create Order Intent API Reference.What to persist
DataWhen
orderIntentIdAlways — every later operation keys off of it.
expiresAtAlways — track the expiry so you can create a new order intent before the permission lapses.
Merchant descriptor (name, url, countryCode)When the card will charge the same merchant repeatedly. You pass it on every credential fetch, so saving it once avoids re-collecting it.
Card credentialsNever — short-lived and merchant-scoped. Fetch fresh on each purchase.
2

Authorize the intent via passkey

If the order intent’s phase is requires-verification, the user must authorize the spending with their passkey. Use the OrderIntentVerification component:
import { OrderIntentVerification } from "@crossmint/client-sdk-react-ui";

function AuthorizeSpending({ orderIntent }: { orderIntent: any }) {
    return (
        <OrderIntentVerification
            orderIntent={orderIntent}
            onVerificationComplete={() => {
                console.log("Permission is now active");
            }}
            onVerificationError={() => {
                console.error("Spending authorization failed");
            }}
        />
    );
}
This step is passkey-only. The user does not receive an email code — the one-time email verification was completed during enrollment, and the device is already bound.After onVerificationComplete fires, the order intent’s phase changes to active and the permission is ready — secure card numbers can now be retrieved.
An order intent moves through requires-verification → active → expired. For the full phase semantics, see the Get Order Intent API Reference. 
{
    "orderIntentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "phase": "requires-verification",
    "payment": {
        "paymentMethodId": "pm_abc123"
    },
    "mandates": [
        {
            "type": "maxAmount",
            "value": "150.00",
            "details": { "currency": "usd", "period": "monthly" }
        },
        {
            "type": "description",
            "value": "Weekly grocery purchases"
        }
    ],
    "expiresAt": "2030-01-01T00:00:00Z",
    "verificationConfig": {
        "environment": "test",
        "publicApiKey": "YOUR_PUBLIC_API_KEY",
        "agentId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "instructionId": "instr_xyz789"
    }
}
For the full order intent API schema, see the Create Order Intent API Reference.

​
Common Gotchas

If the paymentMethodId has not been verified for agentic use, the order intent creation call will fail. Confirm status: "active" on the verification before creating an order intent.
If you do not pass expiresAt when creating the order intent, the permission defaults to seven days from creation. This applies regardless of the mandate period (weekly, monthly, or yearly). Always set expiresAt explicitly when the permission should remain valid beyond seven days.
Unless the response returns phase: "active" immediately, do not reuse a previous verification — each order intent has its own authorization.
A denied or failed verification leaves the order intent in requires-verification. Do not attempt to fetch credentials until the phase is active.

​
Next Steps

Retrieve Secure Card Numbers

Fetch a secure one-time card number, expiration, and CVC to complete a purchase.

Remove Cards

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