After you create a payment session with POST /payment/session, CartAI sends a webhook event to your configured endpoint each time the session changes status. Use these events to find out when the customer has approved the payment, when you can retrieve credentials, and when the session is no longer usable. You don't need to poll for status.
This page covers the events and payloads specific to payment sessions. For endpoint setup, authentication, and expected responses, see Webhooks (general).
Event Lifecycle
CartAI sends one webhook event per status change. Every event carries the sessionId that POST /payment/session returned, so you can match events to your own records.
The normal sequence for a session that is used:
created → approved → utilised → purged
A session that isn't used before its authorization.expiry:
created → expired → purged
approved → expired → purged
| Status | Description | What to do |
|---|---|---|
created | The payment session has been created and the hosted payment url is ready. The customer has not completed the payment flow yet. | Show the customer the hosted url, if you haven't already. |
approved | The customer completed the hosted payment flow (Visa Intelligent Commerce or Mastercard Agent Pay) and authorized the payment. | Action required. Call POST /payment/session/credentials with the sessionId to retrieve the payment credentials. |
utilised | The session's payment credentials have been used. | Mark the session as used in your records. |
expired | The session passed its authorization.expiry before it was used. The hosted url no longer works, and credentials can no longer be retrieved. | Create a new payment session if the customer still needs to pay. |
purged | The session's data has been permanently removed from CartAI. Terminal state. | Remove any remaining references to the session. |
Only callPOST /payment/session/credentialsafter you receiveapproved. Don't call it before the session is approved.
Payload Schema
Every payment session webhook has the same JSON structure, whatever the status.
Top-level fields
| Field | Type | Description |
|---|---|---|
entity | string | The kind of object the event is about. Always "payment_session" for these events. Use this to route events if several webhook types are sent to the same endpoint. |
status | string | The status change that triggered this webhook. See Event Lifecycle for all values. |
timestamp | string (ISO 8601) | When this event was generated. |
sessionId | string (UUID) | The payment session ID. Matches the sessionId returned by POST /payment/session. |
url | string | The hosted payment URL for this session, the same one returned by POST /payment/session. |
corporateId | integer | Your CartAI account identifier. |
mode | string | "production" or "test", depending on the environment the session was created in. |
created_at | string (ISO 8601) | When the payment session was created. |
merchantName | string | null | Name of the merchant tied to the session, if known. null otherwise. |
merchantUrl | string | null | Website URL of the merchant tied to the session, if known. null otherwise. |
authorization | object | The amount and terms the customer is asked to authorize. See authorization. |
authorization
authorization| Field | Type | Description |
|---|---|---|
price | string | The authorized payment amount (e.g. "150"). |
currency | string | Currency code (always "USD"). |
purpose | string | The purpose you set when creating the session, returned unchanged. |
expiry | string (ISO 8601) | When the session expires. If it hasn't been used by then, CartAI sends an expired event. |
Full Payload Example
Below is an approved event from a test-mode session:
{
"url": "https://qa.wallet.cartai.ai?token=<jwt_token>&type=bt&mode=t&w=f&mpr=f",
"sessionId": "01a1e40b-bae6-7930-b585-df16b024751a",
"corporateId": 3,
"mode": "test",
"created_at": "2026-11-16T11:08:56.438681",
"merchantName": null,
"merchantUrl": null,
"authorization": {
"price": "150",
"currency": "USD",
"purpose": "CartAI's Purchase Agent",
"expiry": "2026-11-23T10:03:26.071471+00:00"
},
"status": "approved",
"entity": "payment_session",
"timestamp": "2026-11-16T11:09:52.757156"
}Handling Each Payment Session Event
Below is suggested handler logic for each payment session event.
Deduplicating events
CartAI may deliver the same event more than once. Use sessionId + status as a combined key to spot and skip duplicates. This matters most for approved, so that you don't request credentials twice.
async function isDuplicate(payload) {
const key = `${payload.sessionId}:${payload.status}`;
if (await cache.get(key)) return true;
await cache.set(key, true, { ex: 86400 }); // 24h TTL
return false;
}Example handler
app.post("/webhook", async (req, res) => {
res.status(200).json({ received: true }); // Always acknowledge first
const payload = req.body;
if (payload.entity !== "payment_session") return; // Not a payment session event
if (await isDuplicate(payload)) return;
const { sessionId, status } = payload;
switch (status) {
case "created":
// Session is ready; the customer can open the hosted URL
updatePaymentStatus(sessionId, "awaiting_customer");
break;
case "approved":
// ✅ Customer authorized the payment: retrieve credentials
const credentials = await fetchPaymentCredentials(sessionId);
await continuePurchase(sessionId, credentials);
break;
case "utilised":
// Credentials have been used
updatePaymentStatus(sessionId, "utilised");
break;
case "expired":
// Session expired before use; create a new one if still needed
updatePaymentStatus(sessionId, "expired");
notifyCustomerPaymentExpired(sessionId);
break;
case "purged":
// Session data has been removed from CartAI
cleanUpPaymentSession(sessionId);
break;
}
});
async function fetchPaymentCredentials(sessionId) {
const res = await fetch("https://api.cartai.ai/payment/session/credentials", {
method: "POST",
headers: {
"x-api-key": process.env.CARTAI_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ sessionId }),
});
const { data } = await res.json();
return data;
}
Handle credentials carefully. Never log, store, or send raw payment credentials to the client. Retrieve them on your backend only when you are about to use them.
Event handling summary
| Status | Recommended action |
|---|---|
created | Informational. Make sure the customer has the hosted url. |
approved | Action required. Call POST /payment/session/credentials and continue the purchase. |
utilised | Mark the session as used. |
expired | Mark the session as expired. Create a new session if the customer still needs to pay. |
purged | Clean up any remaining references to the session. |