Handling MFA with Interactive Checkout

For most automated checkouts, that is where the purchase stops. With Interactive Checkout, the CartAI agent pauses, asks your customer for the code in real time, and continues the order once it has it

Many merchants protect their customers' accounts with multi-factor authentication (MFA). When the customer signs in, the merchant texts or emails a one-time password (OTP), and checkout can't continue until someone types it in.

For most automated checkouts, that is where the purchase stops. With Interactive Checkout, the CartAI agent pauses, asks your customer for the code in real time, and continues the order once it has it. Your customer stays signed in to their own account and earns their loyalty points, and the order still goes through.


Why It Matters

  • No dead ends at login. Merchants that require sign-in and MFA no longer block the order.
  • The customer's own account. Orders are placed while signed in to the customer's merchant account, so order history, saved addresses, and rewards stay with them.
  • Works the way you want. Use CartAI's ready-made OTP screen with no UI work, or build the prompt into your own app.
  • Real-time. The agent asks for the code the moment the merchant requests it, while it is still valid.

How It Works

Your App              CartAI Agent              Merchant            Customer
    │                      │                        │                   │
    │── POST /checkout ───►│                        │                   │
    │   (both flags on)    │── Signs in with ──────►│                   │
    │                      │   saved credentials    │── Sends OTP ─────►│
    │                      │◄── Asks for OTP ───────│                   │
    │◄── Webhook with ─────│                        │                   │
    │    requiredInputs    │                        │                   │
    │                      │                        │                   │
    │── Ask customer for OTP ──────────────────────────────────────────►│
    │◄─────────────────────────────────────────────── Customer enters OTP│
    │                      │                        │                   │
    │── OTP reaches agent ►│── Enters OTP ─────────►│                   │
    │                      │── Completes checkout ─►│                   │
    │◄── Webhook: COMPLETED│                        │                   │
  1. Turn it on. Create the checkout task with useSavedCredentialToLogin and allowInteraction both set to true.
  2. The agent signs in. It uses the customer's saved merchant login, and the merchant sends an OTP.
  3. CartAI asks for the code. You receive a webhook with a requiredInputs array.
  4. Collect the OTP. Use CartAI's hosted screen (recommended), or your own UI.
  5. The checkout continues. The agent enters the code and completes the order.

Before You Begin

  • A webhook endpoint configured in the CartAI Admin Portal. This is how CartAI asks for the OTP. See Webhooks.
  • The customer's merchant login saved in the CartAI Credential Vault, using the same email you'll use at checkout. See Create Credential Vault Session.

Step 1 — Turn On Interactive Checkout

When you create the checkout task, set both of these flags in options:

FlagWhat it does
useSavedCredentialToLoginThe agent signs in to the merchant's site with the customer's saved login. This is the step where merchants ask for MFA.
allowInteractionThe agent is allowed to pause and ask your customer for input, instead of failing the task.
📌

Both flags are required. Interactive Checkout currently only works when useSavedCredentialToLogin and allowInteraction are both true.

curl --location 'https://api.cartai.ai/checkout' \
  --header 'x-api-key: YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer": {
      "contact": {
        "firstName": "Carol",
        "lastName": "Sturka",
        "email": "[email protected]",
        "phone": "+12144444444"
      },
      "shippingAddress": {
        "addressLine1": "609 Royal Crest Dr",
        "addressLine2": "",
        "city": "Richardson",
        "province": "TX",
        "postalCode": "75081",
        "country": "US"
      },
      "shippingMethod": { "strategy": "cheapest" },
      "payment": {
        "provider": "test",
        "data": {
          "cardNumber": "4242424242424242",
          "expiryMonth": "12",
          "expiryYear": "2034",
          "cvv": "444",
          "name": "Carol Sturka"
        }
      }
    },
    "tasks": [
      {
        "url": "https://saltiebeauty.com/products/sea-salt-texturizing-spray-enriched-with-sea-salt-marine-botanicals-8-fl-oz-250-ml",
        "quantity": 1
      }
    ],
    "options": {
      "useSavedCredentialToLogin": true,
      "allowInteraction": true
    }
  }'
💡

The customer.contact.email must match the email the merchant login was saved under in the Credential Vault.


Step 2 — Receive the OTP Request

When the merchant asks for an OTP, the agent pauses and CartAI sends a checkout task webhook with a requiredInputs array:

{
  "tid": "01a1e420-877c-7ae0-b8ab-61d16a8c6df4",
  "merchant": "saltiebeauty.com",
  "requiredInputs": [
    {
      "type": "hosted-screen",
      "intent": "mfa-request",
      "required": true,
      "value": "https://credshield.cartai.ai?isMfaFlow=true&taskId=01a1e420-877c-7ae0-b8ab-61d16a8c6df4&token=<jwt_token>",
      "inputSchema": {
        "type": "object",
        "properties": {
          "otp": {
            "type": "string",
            "title": "OTP",
            "maxLength": 8,
            "minLength": 4
          }
        },
        "required": ["otp"]
      }
    }
  ]
}

(Other webhook fields are left out for brevity. See Checkout Task Webhooks for the full payload.)

Each request gives you two ways to collect the code:

FieldUse it for
valueOption A: the URL of CartAI's ready-made OTP screen.
inputSchemaOption B: a description of the fields to collect, so you can build your own form.
⏱️

Act fast. OTPs expire quickly. Notify your customer as soon as the webhook arrives.


Step 3 — Collect the OTP From Your Customer

Option A: Use the CartAI-Hosted Screen (Recommended)

The quickest way to go live. Show the customer the URL from value, either embedded in an iframe or opened in a new window. The screen asks for the OTP and sends it to the agent for you. No extra API calls are needed.

<iframe
  src="https://credshield.cartai.ai?isMfaFlow=true&taskId=...&token=..."
  width="400"
  height="500"
  style="border: none;"
  title="Verify your account"
></iframe>
// In your webhook handler
const mfa = payload.requiredInputs?.find((i) => i.intent === "mfa-request");
if (mfa) {
  notifyCustomer(payload.tid, { verifyUrl: mfa.value }); // e.g. push notification, in-app banner
}

That's it. Once the customer enters the code, the checkout continues on its own. Skip ahead to Step 5.

Option B: Build Your Own OTP Prompt

Want the prompt to match your app exactly? Build it from inputSchema:

  • Each key in properties is a field to show. Here, a single field called otp.
  • title is the label (OTP).
  • minLength and maxLength are the validation rules (4–8 characters).
  • Every field in the schema's required list must be filled in.
// In your webhook handler
const mfa = payload.requiredInputs?.find((i) => i.intent === "mfa-request");
if (mfa) {
  showOtpPrompt(payload.tid, mfa.inputSchema); // render your own form
}

With Option B, you also need to send the code to CartAI yourself. That's Step 4.


Step 4 — Send the OTP to the Agent (Option B Only)

Using the hosted screen from Option A? Skip this step. The screen already sent the code.

When your customer submits the code in your own UI, send it to the agent with Send Interactive Inputs:

curl --location 'https://api.cartai.ai/checkout/01a1e420-877c-7ae0-b8ab-61d16a8c6df4/mfa' \
  --header 'x-api-key: YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{ "otp": "482913" }'

A successful request returns 201:

{
  "status": "success",
  "message": "OTP submitted.",
  "tasks": [
    {
      "taskId": "01a1e420-877c-7ae0-b8ab-61d16a8c6df4",
      "executionId": "0193f2a1-8d5f-7c3b-8e2a-4f6b7c8d9e01",
      "status": "mfa_received"
    }
  ]
}

A few things to know:

  • Send only otp in the body. Extra fields return 400.
  • Send it once. A second submission for the same task returns 409.
  • Send it from your backend. Never expose your API key in client-side code.

Step 5 — Follow the Checkout to Completion

Once the agent has the code, it signs in and carries on with the checkout. Keep listening for checkout task webhooks. A COMPLETED event means the order went through, and FAILED means it couldn't be completed, for example if the merchant rejected the code.


Which Option Should I Choose?

Option A: Hosted ScreenOption B: Your Own UI
Build effortMinimal. Just show a URL.Build a form and call one API.
Look and feelCartAI's screenFully matches your app
Sending the OTPDone for youYou call Send Interactive Inputs
Best forGoing live fastFully branded, native experiences

Quick Checklist

  • ✅ Customer's merchant login saved in the Credential Vault
  • ✅ Webhook endpoint configured in the Admin Portal
  • ✅ options.useSavedCredentialToLogin: true and options.allowInteraction: true on the checkout task
  • ✅ Webhook handler checks every event for requiredInputs
  • ✅ Customer is notified right away (OTPs expire fast)
  • ✅ Option B only: OTP sent with Send Interactive Inputs


Did this page help you?