Payment Session Webhooks

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
StatusDescriptionWhat to do
createdThe 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.
approvedThe 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.
utilisedThe session's payment credentials have been used.Mark the session as used in your records.
expiredThe 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.
purgedThe session's data has been permanently removed from CartAI. Terminal state.Remove any remaining references to the session.
⚠️

Only call POST /payment/session/credentials after you receive approved. 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

FieldTypeDescription
entitystringThe 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.
statusstringThe status change that triggered this webhook. See Event Lifecycle for all values.
timestampstring (ISO 8601)When this event was generated.
sessionIdstring (UUID)The payment session ID. Matches the sessionId returned by POST /payment/session.
urlstringThe hosted payment URL for this session, the same one returned by POST /payment/session.
corporateIdintegerYour CartAI account identifier.
modestring"production" or "test", depending on the environment the session was created in.
created_atstring (ISO 8601)When the payment session was created.
merchantNamestring | nullName of the merchant tied to the session, if known. null otherwise.
merchantUrlstring | nullWebsite URL of the merchant tied to the session, if known. null otherwise.
authorizationobjectThe amount and terms the customer is asked to authorize. See authorization.

authorization

FieldTypeDescription
pricestringThe authorized payment amount (e.g. "150").
currencystringCurrency code (always "USD").
purposestringThe purpose you set when creating the session, returned unchanged.
expirystring (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

StatusRecommended action
createdInformational. Make sure the customer has the hosted url.
approvedAction required. Call POST /payment/session/credentials and continue the purchase.
utilisedMark the session as used.
expiredMark the session as expired. Create a new session if the customer still needs to pay.
purgedClean up any remaining references to the session.