Creates a secure, hosted payment session and returns a URL you can embed in your web application. When the customer opens the URL, CartAI automatically starts Visa Intelligent Commerce or Mastercard Agent Pay based on the card on file — no additional integration required.

How it Works

Calling POST /payment/session provisions a time-limited payment session tied to a specific customer and amount. The flow is:

1. Your backend calls this endpoint with the customer's email, the amount, and the purpose.
2. CartAI returns a sessionId and a hosted url.
3. You embed or redirect the customer to that URL.
4. CartAI detects the customer's card network and launches the appropriate agentic payment flow — Visa Intelligent Commerce or Mastercard Agent Pay.
5. The session expires automatically after 7 days (or at the expiry timestamp in the response).

⚠️

Never expose your API key in client-side code. Always call this endpoint from your backend and pass only the resulting URL to your frontend.

Authentication

Every request must include your API key in the request header.

x-api-key: YOUR_API_KEY_HERE

To get your API key, generate it from the CartAI Admin Portal after your account is provisioned. Contact the CartAI Account Management Team to request access.

Request Body

Full Request Example

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": "700",
      "purpose": "Carol'\''s Purchase Agent"
  }'

Response

A successful request returns HTTP 200 with the following body.

{
  "status": "success",
  "code": 200,
  "message": "Payment session created successfully",
  "data": {
    "url": "https://wallet.cartai.ai?token=<jwt_token>&type=bt&mode=p",
    "sessionId": "019ed477-7954-7d92-8884-d442d1f91549",
    "mode": "production",
    "created_at": "2026-06-17T07:24:20.497354",
    "authorization": {
      "price": "700",
      "currency": "USD",
      "purpose": "Carol's Purchase Agent",
      "expiry": "2026-06-24T07:20:32.875162+00:00"
    }
  }
}

Response Fields

Embedding the Payment URL

The url returned in the response is designed to be embedded directly in your web application. You can open it in a new tab, an iframe, or a modal.

<!-- Open in a new tab -->
<a href="SESSION_URL" target="_blank">Complete Payment</a>

// Redirect the current page
window.location.href = sessionData.data.url;

// Or open in a popup
window.open(sessionData.data.url, '_blank', 'width=480,height=640');

💡

Tip: Store the sessionId before redirecting so you can reconcile the completed payment against your order when you receive the webhook callback.

Agentic Payment Networks

CartAI automatically selects the payment network based on the card associated with the customer's email:

No additional configuration is needed — the hosted URL handles network detection transparently.

Testing

To test the payment flow end-to-end without using a real card, use the following test credentials:

⚠️

Test sessions only work against the QA environment (https://qa.api.cartai.ai). Do not use test cards against the production endpoint.

Error Reference