---
updatedAt: 2026-11-17T18:17:44.000Z
agentTools:
  projectIndex: https://docs.cartai.ai/llms.txt
---

# Create Payment Session

Creates a hosted payment session that generates a secure URL for embedding in your web application. The session initiates Visa Intelligent Commerce or Mastercard Agent Pay based on the customer's card. Share the returned URL with the customer to complete payment.

###

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).

<Callout icon="⚠️" theme="warn">
  ### **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.
</Callout>

***

## Authentication

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

```http
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

| Field     | Type                  | Required | Description                                                                                                                      |
| --------- | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `email`   | string (email format) | ✅ Yes    | The customer's email address. Used to identify the customer and look up their card.                                              |
| `price`   | string                | ✅ Yes    | Payment amount in USD (e.g. `"700"`). Passed as a string — do not include currency symbols.                                      |
| `purpose` | string                | ✅ Yes    | A short description of what the payment is for (e.g. `"Manil's Purchase Agent"`). Shown to the customer during the payment flow. |

***

## Full Request Example

```bash
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

A successful request returns HTTP `200` with the following body.

```json
{
  "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

| Field                         | Type   | Description                                                                                                  |
| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `data.url`                    | string | The hosted payment URL. Embed this in your web app or redirect the customer to it to start the payment flow. |
| `data.sessionId`              | string | Unique identifier for this payment session. Store this to correlate payment events.                          |
| `data.mode`                   | string | `"production"` or `"test"` — reflects the environment the session was created in.                            |
| `data.created_at`             | string | ISO 8601 timestamp of when the session was created.                                                          |
| `data.authorization.price`    | string | The authorized payment amount.                                                                               |
| `data.authorization.currency` | string | Currency code (always `"USD"`).                                                                              |
| `data.authorization.purpose`  | string | The purpose string you provided in the request, echoed back.                                                 |
| `data.authorization.expiry`   | string | ISO 8601 timestamp after which the session URL is no longer valid.                                           |

***

## 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.

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

```javascript
// 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');
```

<Callout icon="💡" theme="default">
  ### **Tip:** Store the `sessionId` before redirecting so you can reconcile the completed payment against your order when you receive the webhook callback.
</Callout>

***

## Agentic Payment Networks

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

| Card Network   | Payment Flow              |
| -------------- | ------------------------- |
| **Visa**       | Visa Intelligent Commerce |
| **Mastercard** | Mastercard Agent Pay      |

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:

| Field       | Value                  |
| ----------- | ---------------------- |
| Card Number | *(Add Test Card here)* |
| Expiry      | *(Add Test Card here)* |
| CVV         | *(Add Test Card here)* |

***

## Error Reference

| HTTP Status | Cause                                         | What to do                                                                 |
| ----------- | --------------------------------------------- | -------------------------------------------------------------------------- |
| `200`       | Session created successfully                  | Use the returned `url` to initiate the payment flow                        |
| `400`       | Missing or invalid fields in the request body | Check that `email`, `price`, and `purpose` are all present and well-formed |
| `401`       | Missing or invalid `x-api-key`                | Verify the header name and that you are using the correct environment key  |
| `429`       | Rate limited                                  | Back off and retry after a delay                                           |
| `5xx`       | CartAI server error                           | Retry with exponential backoff; contact support if it persists             |

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Cart AI",
    "version": "1.0.0",
    "description": ""
  },
  "servers": [
    {
      "url": "https://api.cartai.ai"
    }
  ],
  "paths": {
    "/payment/session": {
      "post": {
        "summary": "Create Payment Session",
        "tags": [],
        "operationId": "create_payment_session",
        "description": "Creates a hosted payment session that generates a secure URL for embedding in your web application. The session initiates Visa Intelligent Commerce or Mastercard Agent Pay based on the customer's card. Share the returned URL with the customer to complete payment.",
        "parameters": [
          {
            "in": "header",
            "name": "x-api-key",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "price",
                  "purpose"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Customer's email address"
                  },
                  "price": {
                    "type": "string",
                    "description": "Payment amount in USD"
                  },
                  "purpose": {
                    "type": "string",
                    "description": "Description of what the payment is for (e.g. agent name or product)"
                  }
                }
              },
              "examples": {
                "Example": {
                  "summary": "Example",
                  "value": {
                    "email": "customer@example.com",
                    "price": "700",
                    "purpose": "Carol's Purchase Agent"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment session created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "code": {
                      "type": "integer"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string",
                          "description": "Hosted payment URL to embed in your web application. Starts Visa Intelligent Commerce or Mastercard Agent Pay based on the customer's card."
                        },
                        "sessionId": {
                          "type": "string"
                        },
                        "mode": {
                          "type": "string",
                          "enum": [
                            "production",
                            "test"
                          ]
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "authorization": {
                          "type": "object",
                          "properties": {
                            "price": {
                              "type": "string"
                            },
                            "currency": {
                              "type": "string"
                            },
                            "purpose": {
                              "type": "string"
                            },
                            "expiry": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "value": {
                      "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"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          }
        }
      }
    }
  },
  "x-readme": {}
}
```