Payment sessions
How does CartAI handle payments securely?
Your customer enters and authorizes their card on a secure page hosted by CartAI. Card data never touches your servers, your front end, or your logs. Payments run on Visa Intelligent Commerce and Mastercard Agent Pay. CartAI picks the network from the customer’s card.
How do I create a payment session?
Call POST /payment/session from your backend with the customer’s email, the amount, and a purpose. The response includes a hosted payment URL, a sessionId, and an authorization that sets the amount, currency, purpose, and expiry. The customer sees the purpose, so write it clearly. A session is valid until the expiry time returned in the response. If it expires before the customer approves, create a new one.
How do I use a payment session in a checkout?
Send the customer to the hosted payment URL, or embed it in an iframe to keep them on your page. After the customer authorizes, pass the sessionId in the payment object of POST /checkout.
How do I know when a payment session is approved?
CartAI sends a webhook when a session is approved or expires. Configure the endpoint in the portal. Treat approved as the signal that payment is ready. The same event can arrive more than once, so make your handler idempotent.
Can I delete a payment session?
Yes. Send DELETE /payment/session/{sessionId}. The hosted payment URL stops working and the session can no longer be used. Deletion cannot be undone. Delete a session when the customer cancels, when the amount or purpose changes, or when you created a duplicate.
How do I test payments?
Set the payment provider to test and use the test card from the Getting Started guide. Do not use real card details in testing mode. The test provider is disabled on production keys.
CartAI Wallet
What is the CartAI Wallet?
The CartAI Wallet is a secure payment page that CartAI hosts for you. Your customer authorizes a payment there, and CartAI issues payment credentials limited to that authorization. The customer can pay with a Visa or Mastercard agentic token or with their Stripe Link wallet. You can use the Wallet on its own with any checkout, including your own app, your own AI agent, or your existing payment flow. The credentials work at a merchant’s checkout like any other card.
How does the CartAI Wallet work?
Create a payment session with POST /payment/session.
Open the returned URL for the customer in an iframe, a popup, or a new tab.
Wait for the approved webhook.
Call POST /payment/session/credentials with the sessionId to retrieve the credentials.
Use the credentials at the merchant’s checkout. Keep the total within the amount the customer approved.
Make every call from your backend.
What is the difference between an Agentic PAN and the Stripe Link wallet?
The customer chooses how to pay in the Wallet. An Agentic PAN is a network token for agent purchases, issued through Visa Intelligent Commerce or Mastercard Agent Pay. With the Stripe Link wallet, the customer pays from their Link account and a card number is issued for that one payment. Either way, the customer’s real card number is never shared with you or the merchant. Your integration is the same for both.
How should I handle Wallet credentials?
Retrieve credentials only after the approved webhook and only when you are about to use them. Never log them, store them, or send them to the client. Once a session expires or is deleted, its credentials can no longer be retrieved.