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 ──────────────────────────────────────►│
- Create a payment session. Your backend calls
POST /payment/sessionwith the customer's email, the amount, and a purpose. - Open the CartAI Wallet. The customer opens the returned
urland authorizes the payment. - Wait for the
approvedwebhook. CartAI notifies your webhook endpoint when the customer has authorized the payment. - Retrieve the payment credentials. Your backend calls
POST /payment/session/credentialswith thesessionId. - 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 intestmode. 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 PAN | Stripe Link wallet | |
|---|---|---|
| What it is | A 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. |
| Network | Chosen automatically from the customer's card (Visa or Mastercard). | Depends on the card issued. |
| Customer's real card number | Never shared with you or the merchant. | Never shared with you or the merchant. |
| Who chooses | The 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 untilauthorization.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
approved WebhookWhen 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 receiveapproved. 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 field | Credential field |
|---|---|
| Card number | data.info.cardNumber |
| Expiry month | data.info.expiryMonth |
| Expiry year | data.info.expiryYear |
| CVV / security code | data.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
| Problem | Likely cause | What to do |
|---|---|---|
No approved webhook arrives | The customer hasn't finished in the CartAI Wallet, or your webhook endpoint isn't configured | Check that the customer completed the CartAI Wallet flow, and check your webhook setup in the Admin Portal. |
You receive expired instead of approved | The customer didn't approve before authorization.expiry | Create a new payment session and open the new url. |
400 from Get Payment Credentials | Missing or invalid sessionId | Check that you're passing the sessionId from Step 1. |
401 from either API | Missing or invalid x-api-key | Check the header name and that you're using the key for the right environment. |
What Happens Next
Updated about 5 hours ago