Choose a Payment Method

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 `browserProfileId`.
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.

{
    "requestId": "req_123",
    "question": "Authorize a card payment of 42.50 USD at shop.example.com.",
    "expiresAt": "2026-09-24T10:30:00.000Z",
    "interaction": {
        "kind": "payment",
        "purpose": "checkout_payment",
        "method": "card",
        "amount": { "kind": "exact", "value": "42.50", "currency": "USD" },
        "merchant": { "domain": "shop.example.com" }
    }
}

method is the method this request accepts. Today it is always "card".
amount.value is a decimal string and amount.currency is an ISO 4217 code. kind: "exact" is the verified payable total; kind: "maximum" is the run’s cost ceiling.
merchant.domain is the merchant where the credential will be used.

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 omit merchant. Agent Checkouts binds the card credential to the merchant when it requests it.

// Uses action from the required-action handler in the quickstart.
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": "YOUR_CLIENT_API_KEY",
        Authorization: "Bearer YOUR_USER_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.domain}`,
        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.

Verify a card rail when required

Inspect orderIntent.rails for a rail that includes "card" in credentialFormats:

If a card-capable rail has status: "active", continue to the next step.
If the available card-capable rail has status: "pending_verification", follow Verify the Selected Rail to render OrderIntentVerification in your authenticated application.
If the encrypted-card rail has status: "pending_cvc_recollection", follow Recollect the CVC before fetching the order intent again.
If every card-capable rail has status: "error", ask the user for another registered card.

After verification, fetch the order intent again and confirm that a card-capable rail is active before submitting its ID:

const response = await fetch(
    `https://www.crossmint.com/api/unstable/order-intents/${orderIntent.orderIntentId}`,
    {
        headers: {
            "X-API-KEY": "YOUR_CLIENT_API_KEY",
            Authorization: "Bearer YOUR_USER_JWT",
        },
    }
);

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

orderIntent = await response.json();

const hasActiveCardRail = orderIntent.rails.some(
    (rail) => rail.status === "active" && rail.credentialFormats.includes("card")
);

if (!hasActiveCardRail) {
    throw new Error("The order intent does not have an active card rail");
}

For a web or native application, show verification inline or in a webview. For a messaging or voice integration, send the user to an authenticated page in your application and resume the conversation after the rail becomes active.

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 values, 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.

Connect the Request to Your User Channel

Keep the checkout protocol separate from the surface where the user authorizes the purchase:

Integration	Recommended handoff
Web application	Render authorization and any rail verification inline.
Native application	Open a native screen or authenticated webview, then return the order intent ID to the agent runtime.
Messaging or voice agent	Explain the amount and merchant in the conversation, then send an authenticated link or deep link to your secure authorization surface. Resume the conversation when it succeeds.
Fully autonomous server agent	Apply authorization policy on the server. Escalate to a user surface only when policy or rail verification requires it.

The agent runtime submits only the orderIntentId. The channel does not need to display the checkout browser or collect card data.

How Card Data Stays Protected

The card does not pass through your backend or the checkout control plane. The user enters it in a Crossmint-hosted form when you save it. Your application refers to it by paymentMethodId and orderIntentId.
Sensitive response data is sealed. After Crossmint accepts the response, subsequent run and message reads report that authorization was provided and whether it was applied. They do not return the order intent ID or card details to the model or message history.
The credential is scoped to the purchase. Agent Checkouts requests a card credential only when it is ready to pay, bound to the authorized amount and merchant domain. It fills the merchant’s card fields without reading them back.

Recover from an Authorization Error

If Agent Checkouts cannot use the order intent, the apply_payment step fails with a typed code and the agent sends a new payment request. Fix the cause, then answer that new request.

Code	Cause	What to do
`order_intent_not_found`	No order intent with this ID exists for the run’s environment, project, and user.	Create the order intent in the same environment and project, for the same user as the run.
`order_intent_expired`	The order intent expired.	Create a new order intent and submit its ID.
`order_intent_cancelled`	The order intent was cancelled or revoked.	Create a new order intent and submit its ID.
`verification_required`	The selected rail still needs user verification.	Render `OrderIntentVerification`, wait for the rail to become `active`, and submit the ID to the new request.
`rail_unavailable`	No rail on the order intent can currently issue a card credential.	Recollect the CVC if the encrypted-card rail requires it. Otherwise, register the card again or ask the user for another card.
`insufficient_allowance`	The order intent amount is below the payable total.	Create a new order intent for the amount in the new payment request.
`provider_error`	Crossmint or the card network could not issue the credential.	Retry with a new authorization. Contact support if the error persists.

If the merchant declines the card, the checkout ends as blocked with merchant.payment_declined.

Introduction

Agent Cards

Agent Wallets

Agent Checkouts

API Reference

Prerequisites

Choose the Method in the Task

Authorize an Agent Card

Connect the Request to Your User Channel

How Card Data Stays Protected

Recover from an Authorization Error

Next Steps

Create an Agent Card

Buy from Authenticated Stores

​Prerequisites

​Choose the Method in the Task

​Authorize an Agent Card

​Connect the Request to Your User Channel

​How Card Data Stays Protected

​Recover from an Authorization Error

​Next Steps

Create an Agent Card

Buy from Authenticated Stores

Prerequisites

Choose the Method in the Task

Authorize an Agent Card

Connect the Request to Your User Channel

How Card Data Stays Protected

Recover from an Authorization Error

Next Steps