Payment

CartAI supports two ways to pass payment information when creating a checkout task. Choose the approach that fits your use case — Test Payment for development and QA, and Secure Payment for production flows where the customer provides their card details through a hosted, PCI-compliant UI.

Option 1 — Test Payment

Use this approach during development to run checkout tasks without a real card. Pass card details directly in the customer.payment object of your POST /checkout request.

Set provider to "test" and supply the card details inside data.

{
  "customer": {
    "payment": {
      "provider": "test",
      "data": {
        "cardNumber": "4242424242424242",
        "expiryMonth": "12",
        "expiryYear": "2034",
        "cvv": "444",
        "name": "Carol Sturka"
      }
    }
  }
}

Test Payment Fields

⚠️

Never use test card details in production. The "test" provider is disabled on production API keys.

Option 2 — Secure Payment (Recommended for Production)

For production, card details should never pass through your backend. Instead, use the Create Payment Session API to generate a hosted payment URL, let the customer complete the payment flow there, and then pass the resulting sessionId to POST /checkout.

Step 1 — Create a Payment Session

Call POST /payment/session from your backend to generate a session.

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:

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

Step 2 — Redirect the Customer to the Hosted Payment Flow

Pass the url to your frontend and present it to the customer. CartAI automatically starts Visa Intelligent Commerce or Mastercard Agent Pay based on the customer's card.

You can deliver the payment UI in whichever way fits your application:

Redirect — navigate the customer directly to the hosted page.

window.location.href = sessionData.data.url;

Embed in an iframe — keep the customer on your page while the payment flow runs inside a contained widget.

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

// Dynamically set the src after fetching the session
document.getElementById('payment-frame').src = sessionData.data.url;

The customer completes the payment authorization on CartAI's hosted UI. No card data touches your servers.

Step 3 — Use the sessionId in Create Checkout

Once the customer has completed the hosted payment flow, pass the sessionId in the customer.payment object when creating the checkout task.

{
  "customer": {
    "payment": {
      "data": {
        "sessionId": "019ed477-7954-7d92-8884-d442d1f91549"
      }
    }
  }
}

CartAI looks up the authorized payment session by ID and uses it to process the order — no raw card data required.

Comparison