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

Field	Type	Description
`provider`	string	Must be `"test"` to use the test payment flow.
`cardNumber`	string	Test card number.
`expiryMonth`	string	Two-digit expiry month (e.g. `"12"`).
`expiryYear`	string	Four-digit expiry year (e.g. `"2034"`).
`cvv`	string	Three or four-digit card verification value.
`name`	string	Cardholder name as it appears on the card.

⚠️
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": "customer@example.com",
      "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;

💡
Tip: Use the allow="payment" attribute on the iframe so the browser grants the hosted page access to the Payment Request API if needed.

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.

💡
Tip: Store the sessionId as soon as you receive it in Step 1 so it is available to attach to the checkout task after the customer completes Step 2.

Comparison

	Test Payment	Secure Payment
Use case	Development & QA	Production
Card data in request	Yes	No — handled by hosted UI
Payment network	Test only	Visa Intelligent Commerce / Mastercard Agent Pay
PCI scope	Not applicable	Out of scope for your backend
`provider` field	`"test"`	Omit — identified via `sessionId`