Standalone CartAI Wallet

You can use the CartAI Wallet on its own, with any checkout. Your app, your own AI agent, or your existing payment flow uses the credentials to pay at the merchant's checkout like any other card.

The CartAI Wallet lets your customers authorize a payment without you ever collecting or storing their raw card details. The customer authorizes the payment once in the CartAI Wallet, a secure payment page that CartAI hosts for you. CartAI then issues payment credentials scoped to that authorization: either an Agentic PAN from Visa or Mastercard, or a card from the customer's Stripe Link wallet, depending on what the customer chooses.

You can use the CartAI Wallet on its own, with any checkout. Your app, your own AI agent, or your existing payment flow uses the credentials to pay at the merchant's checkout like any other card.

This guide walks through the full flow, from creating a payment session before checkout to retrieving the credentials once the customer has approved.


When to Use the Standalone CartAI Wallet

  • You run your own checkout, such as your own shopping agent, browser automation, or in-app purchase flow, and need card credentials the customer has explicitly authorized.
  • You want your customers to pay with Visa Intelligent Commerce or Mastercard Agent Pay without building those integrations yourself.
  • You want to keep raw card data off your servers.

How It Works

Your Backend           CartAI              Customer          Merchant Checkout
     │                    │                    │                     │
     │─ POST /payment/session ─►│              │                     │
     │◄─ { sessionId, url } ─│                 │                     │
     │                    │                    │                     │
     │─ Open CartAI Wallet url ──────────────►│                     │
     │                    │◄─ Authorizes payment │                   │
     │                    │   (Agentic PAN or  │                     │
     │                    │ Stripe Link wallet)│                     │
     │                    │                    │                     │
     │◄─ Webhook: "approved" ─│                │                     │
     │                    │                    │                     │
     │─ POST /payment/session/credentials ─►│  │                     │
     │◄─ { card credentials } ─│               │                     │
     │                    │                    │                     │
     │─ Pay with credentials ──────────────────────────────────────►│
  1. Create a payment session. Your backend calls POST /payment/session with the customer's email, the amount, and a purpose.
  2. Open the CartAI Wallet. The customer opens the returned url and authorizes the payment.
  3. Wait for the approved webhook. CartAI notifies your webhook endpoint when the customer has authorized the payment.
  4. Retrieve the payment credentials. Your backend calls POST /payment/session/credentials with the sessionId.
  5. Pay at checkout. Use the credentials at the merchant's checkout.

Before You Begin

  • You have a CartAI API key. See Getting Started.
  • You have a webhook endpoint configured in the CartAI Admin Portal. See Webhooks.
  • All API calls in this guide are made from your backend. Never expose your API key in client-side code.
⚠️

Testing: if your account hasn't been activated for production yet, payment sessions run in test mode. Don't use real card details while testing.


Agentic PAN vs Stripe Link Wallet

In the CartAI Wallet, the customer chooses how they want to pay. CartAI supports two kinds of credentials:

Agentic PANStripe Link wallet
What it isA network token issued for AI-agent purchases through Visa Intelligent Commerce or Mastercard Agent Pay.A card number issued for this payment from the customer's Stripe Link wallet.
NetworkChosen automatically from the customer's card (Visa or Mastercard).Depends on the card issued.
Customer's real card numberNever shared with you or the merchant.Never shared with you or the merchant.
Who choosesThe customer, in the CartAI Wallet.The customer, in the CartAI Wallet.

Your integration doesn't change based on the customer's choice. You create the session, wait for approved, and retrieve the credentials the same way in both cases.


Step 1 — Create a Payment Session

Before the customer checks out, create a payment session from your backend. Set price to the amount the customer is authorizing for this purchase.

curl --location 'https://api.cartai.ai/payment/session' \
  --header 'x-api-key: YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "email": "[email protected]",
      "price": "150",
      "purpose": "Order #1042 from Acme Shopping Assistant"
  }'

Response:

{
  "status": "success",
  "code": 200,
  "message": "Payment session created successfully",
  "data": {
    "url": "https://wallet.cartai.ai?token=<jwt_token>&type=bt&mode=p",
    "sessionId": "01a1e40b-bae6-7930-b585-df16b024751a",
    "mode": "production",
    "created_at": "2026-11-16T11:08:56.438681",
    "authorization": {
      "price": "150",
      "currency": "USD",
      "purpose": "Order #1042 from Acme Shopping Assistant",
      "expiry": "2026-11-23T10:03:26.071471+00:00"
    }
  }
}

The customer sees purpose in the CartAI Wallet, so make it clear what they're paying for.

Store the sessionId with your order before going further. Every later step and webhook event uses it.

See Create Payment Session for the full API reference.


Step 2 — Open the CartAI Wallet for the Customer

Send the url to your frontend and open it for the customer. The CartAI Wallet detects the customer's card network, lets them choose between an Agentic PAN and their Stripe Link wallet, and collects their authorization. No card data touches your servers.

Embed in an iframe to keep the customer on your page:

<iframe
  src="SESSION_URL"
  width="480"
  height="640"
  style="border: none;"
  allow="payment"
  title="CartAI Wallet"
></iframe>

Or open it in a popup or a new tab:

window.open(sessionData.data.url, "_blank", "width=480,height=640");
💡

The session stays valid until authorization.expiry (7 days after creation by default). If it expires before the customer approves, create a new session.


Step 3 — Wait for the approved Webhook

When the customer finishes in the CartAI Wallet, CartAI sends a payment session webhook to your endpoint with status: "approved":

{
  "entity": "payment_session",
  "status": "approved",
  "sessionId": "01a1e40b-bae6-7930-b585-df16b024751a",
  "mode": "production",
  "authorization": {
    "price": "150",
    "currency": "USD",
    "purpose": "Order #1042 from Acme Shopping Assistant",
    "expiry": "2026-11-23T10:03:26.071471+00:00"
  },
  "timestamp": "2026-11-16T11:09:52.757156"
}

(Some fields are left out for brevity. See Payment Session Webhooks for the full payload and every status.)

Use the sessionId to find the matching order in your system.

⚠️

Don't retrieve credentials before you receive approved. The session must be authorized by the customer first.


Step 4 — Retrieve the Payment Credentials

Once the session is approved, call POST /payment/session/credentials from your backend. Pass merchantUrl when you know which merchant the credentials will be used on.

curl --location 'https://api.cartai.ai/payment/session/credentials' \
  --header 'x-api-key: YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
      "sessionId": "01a1e40b-bae6-7930-b585-df16b024751a",
      "merchantUrl": "https://saltiebeauty.com"
  }'

Response:

{
  "status": "success",
  "code": 200,
  "message": "Payment credentials retrieved and securely delivered",
  "data": {
    "type": "card",
    "info": {
      "cardNumber": "4242424242424242",
      "cvv": "234",
      "expiryMonth": "04",
      "expiryYear": "2027"
    }
  }
}

The response has the same shape whether the customer chose an Agentic PAN or their Stripe Link wallet, so you can handle both with the same code.

See Get Payment Credentials for the full API reference.

⚠️

Handle credentials carefully. Retrieve them only when you are about to use them. Never log them, store them, or send them to the client.


Step 5 — Pay at the Merchant's Checkout

Use the credentials wherever your checkout collects card details. This could be the merchant's payment form, filled in by your agent or automation, or your own payment processor integration. Map the response fields like this:

Checkout fieldCredential field
Card numberdata.info.cardNumber
Expiry monthdata.info.expiryMonth
Expiry yeardata.info.expiryYear
CVV / security codedata.info.cvv

Keep the purchase total within the authorization.price the customer approved.


Putting It Together

// 1. Create a payment session before checkout
app.post("/orders/:orderId/payment", async (req, res) => {
  const order = await getOrder(req.params.orderId);

  const response = await fetch("https://api.cartai.ai/payment/session", {
    method: "POST",
    headers: {
      "x-api-key": process.env.CARTAI_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: order.customerEmail,
      price: String(order.total),
      purpose: `Order #${order.id} from Acme Shopping Assistant`,
    }),
  });
  const { data } = await response.json();

  await saveSessionId(order.id, data.sessionId);

  // 2. Send the CartAI Wallet URL to the frontend
  res.json({ walletUrl: data.url });
});

// 3. Wait for the approved webhook
app.post("/webhook", async (req, res) => {
  res.status(200).json({ received: true }); // Always acknowledge first

  const event = req.body;
  if (event.entity !== "payment_session" || event.status !== "approved") return;

  const order = await findOrderBySessionId(event.sessionId);

  // 4. Retrieve the payment credentials
  const credRes = await fetch("https://api.cartai.ai/payment/session/credentials", {
    method: "POST",
    headers: {
      "x-api-key": process.env.CARTAI_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sessionId: event.sessionId,
      merchantUrl: order.merchantUrl,
    }),
  });
  const { data: credentials } = await credRes.json();

  // 5. Pay at the merchant's checkout with your own checkout flow
  await payAtMerchantCheckout(order, credentials.info);
});

Troubleshooting

ProblemLikely causeWhat to do
No approved webhook arrivesThe customer hasn't finished in the CartAI Wallet, or your webhook endpoint isn't configuredCheck that the customer completed the CartAI Wallet flow, and check your webhook setup in the Admin Portal.
You receive expired instead of approvedThe customer didn't approve before authorization.expiryCreate a new payment session and open the new url.
400 from Get Payment CredentialsMissing or invalid sessionIdCheck that you're passing the sessionId from Step 1.
401 from either APIMissing or invalid x-api-keyCheck the header name and that you're using the key for the right environment.

What Happens Next



Did this page help you?