Authorize Payments

Agent Checkouts can use any payment method the merchant accepts. Tell the agent which method to use in the run’s task. If the agent needs a card credential, it pauses and sends a typed payment request for your application to authorize. Your agent runtime can run on a server and communicate through any user channel, including a website, native app, messaging app, or voice assistant. The user only needs a secure application surface when they must authorize or verify the card.

Prerequisites

Agent Checkout integration: Complete the Agent Checkouts quickstart so your application can start a run, observe it, and send messages.
Agent Card setup: To use an Agent Card, save the user’s card, register it, and be ready to create an order intent.
Consistent user identity: Use the same Crossmint project, environment, and user identity for the checkout run and its order intent.

Choose the Method in the Task

Describe the user’s preferred method when you start the run. Be specific enough that the agent does not have to infer which option to select.

Method	Example task	What else to provide
Crossmint Agent Card	`Buy one in black and pay by card.`	Authorize the typed payment request with an order intent.
Card saved at the merchant	`Buy one in black using my saved Visa ending in 4242.`	Start the run with the user’s `browser.profileId`.
Local or alternative method	`Buy one in black and pay with Shop Pay.`	Answer any instructions the merchant presents. If the method is unavailable, steer the run to another method.

The task selects the method. It does not authorize a charge. Only answer a typed payment request when the agent is ready to pay.

Authorize an Agent Card

Detect the payment request

The run moves to awaiting_input and exposes the request in both places you can observe a run:

requiredAction.request when you read the run
an input_request message part when you list or stream messages

Dispatch on interaction.kind === "payment". The request contains safe charge metadata, not card details, an iframe URL, or an order intent ID.An open payment message part looks like this:

{
    "type": "input_request",
    "status": "open",
    "requestId": "req_123",
    "question": "Authorize a card payment of 42.50 USD at shop.example.com.",
    "expiresAt": "2026-10-02T15:30:00.000Z",
    "interaction": {
        "kind": "payment",
        "purpose": "checkout_payment",
        "method": "card",
        "amount": { "kind": "exact", "value": "42.50", "currency": "USD" },
        "merchant": {
            "url": "https://shop.example.com",
            "name": "Example Shop",
            "countryCode": "US"
        }
    }
}

method: "card" requests a card credential.
amount.value is a decimal string and amount.currency is an ISO 4217 code. kind: "exact" is the requested payable total; kind: "maximum" is the run’s cost ceiling.
merchant identifies where the credential will be used. Copy its url, name, and countryCode unchanged when you create the order intent.

Create the order intent

Create the order intent in your authenticated application with a production client-side key that has order-intents.create and order-intents.read scopes. Send the JWT for the same user who owns the saved card and the checkout run.Use the exact amount from the payment request, set a short expiration, and copy interaction.merchant into the order intent. This makes the merchant available to payment rails that need it before credential minting. If you omit it, Agent Checkouts supplies the same merchant when it requests the credential.

// Uses an open payment request from the checkout run.
const runId = "YOUR_RUN_ID";
const apiKey = "YOUR_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";
const checkoutHeaders = { "X-API-KEY": apiKey, Authorization: `Bearer ${jwt}` };
const runResponse = await fetch(
    `https://www.crossmint.com/api/unstable/agent-checkouts/${runId}`,
    { headers: checkoutHeaders }
);
if (!runResponse.ok) {
    throw new Error(`Could not read checkout: ${runResponse.status}`);
}
const run = await runResponse.json();
if (run.status !== "awaiting_input" || run.requiredAction.request.interaction.kind !== "payment") {
    throw new Error("Checkout does not have an open payment request");
}
const action = run.requiredAction;
const paymentRequest = action.request;
const expiresAt = new Date(Date.now() + 2 * 60 * 60 * 1_000).toISOString();

const response = await fetch("https://www.crossmint.com/api/unstable/order-intents", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": apiKey,
        Authorization: `Bearer ${jwt}`,
    },
    body: JSON.stringify({
        paymentMethodId: "YOUR_PAYMENT_METHOD_ID",
        amount: {
            value: paymentRequest.interaction.amount.value,
            currency: paymentRequest.interaction.amount.currency,
        },
        description: `Agent Checkout at ${paymentRequest.interaction.merchant.name}`,
        merchant: paymentRequest.interaction.merchant,
        expiresAt,
    }),
});

if (!response.ok) {
    throw new Error(`Could not create order intent: ${response.status}`);
}

let orderIntent = await response.json();

YOUR_PAYMENT_METHOD_ID is the ID returned when you save and register the user’s card. For the complete request and response, see Create an Agent Card.

Complete verification when required

Read orderIntent.rails and look for an active rail whose credentialFormats includes "card". The top-level order-intent status does not tell you whether a card credential is ready.If no card rail is active, follow Verify the Selected Rail for pending_verification, or Recollect the CVC for pending_cvc_recollection. Fetch the order intent again after that step and confirm that a card-capable rail is active. If none can become active, ask the buyer for another card.The Agent Card guide shows the verification component. Card setup and verification are separate from submitting the checkout response.

Submit the order intent ID

Send one input_response part that references the request’s requestId. Do not send card numbers, expiration dates, or security codes.

{
    "id": "msg_7f3c9a",
    "parts": [
        {
            "type": "input_response",
            "requestId": "req_123",
            "action": "submit",
            "response": {
                "kind": "payment",
                "orderIntentId": "a1b2c3d4-e5f6-4890-abcd-ef1234567890"
            }
        }
    ]
}

You can instead send action: "alternative" with text such as "Pay with Shop Pay instead", or action: "decline" to refuse the charge. See Send Agent Checkout Message for the complete schema.Answer before the request’s expiresAt. If it expires, observe the run for a new request and answer its new requestId.

Never put card details in the task, a buyer profile, form answers, or a text message. Raw card details are not accepted.

Continue observing the run

The accepted response resumes the run. Continue streaming messages or reading the run until it completes, asks for another input, or stops.If the merchant total changes or the authorization cannot be used, the agent sends a new payment request. Answer the new requestId; do not reuse a response from an earlier request.

Handle Authorization Problems

Submitting the ID acknowledges authorization; it does not confirm that the merchant accepted the card. Follow the run for application outcomes, another request, or the final result.

Condition	Your Next Action
The order intent is expired or revoked	Create a replacement when answering the current open payment request.
No card rail is active	Complete the verification or CVC recollection required by the selected rail; recheck the order intent.
The checkout asks for a new amount or authorization	Use that new request’s amount and merchant when creating the replacement order intent.
The request closed or expired	Read the run again and handle its current action.
The merchant declines the card	The run ends as `blocked` with `result.code: "merchant.payment_declined"`.

Use the same production project and buyer for the run, saved card, and order intent. Your application sends identifiers instead of raw card data. Protected collection does not guarantee that values applied to merchant inputs are absent from later browser observations or recordings. For web, native, messaging, and server integrations, see Connect Your User Channel.

Introduction

Agent Cards

Agent Wallets

Agent Checkouts

API Reference

Prerequisites

Choose the Method in the Task

Authorize an Agent Card

Handle Authorization Problems

Next Steps

Create an Agent Card

Reuse Merchant Sessions

​Prerequisites

​Choose the Method in the Task

​Authorize an Agent Card

​Handle Authorization Problems

​Next Steps

Create an Agent Card

Reuse Merchant Sessions

Prerequisites

Choose the Method in the Task

Authorize an Agent Card

Handle Authorization Problems

Next Steps