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│ │ │
- Turn it on. Create the checkout task with
useSavedCredentialToLoginandallowInteractionboth set totrue. - The agent signs in. It uses the customer's saved merchant login, and the merchant sends an OTP.
- CartAI asks for the code. You receive a webhook with a
requiredInputsarray. - Collect the OTP. Use CartAI's hosted screen (recommended), or your own UI.
- 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:
| Flag | What it does |
|---|---|
useSavedCredentialToLogin | The agent signs in to the merchant's site with the customer's saved login. This is the step where merchants ask for MFA. |
allowInteraction | The 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 whenuseSavedCredentialToLoginandallowInteractionare bothtrue.
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
}
}'
Thecustomer.contact.emailmust 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:
| Field | Use it for |
|---|---|
value | Option A: the URL of CartAI's ready-made OTP screen. |
inputSchema | Option B: a description of the fields to collect, so you can build your own form. |
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
propertiesis a field to show. Here, a single field calledotp. titleis the label (OTP).minLengthandmaxLengthare the validation rules (4–8 characters).- Every field in the schema's
requiredlist 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
otpin the body. Extra fields return400. - 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 Screen | Option B: Your Own UI | |
|---|---|---|
| Build effort | Minimal. Just show a URL. | Build a form and call one API. |
| Look and feel | CartAI's screen | Fully matches your app |
| Sending the OTP | Done for you | You call Send Interactive Inputs |
| Best for | Going live fast | Fully branded, native experiences |
Quick Checklist
- ✅ Customer's merchant login saved in the Credential Vault
- ✅ Webhook endpoint configured in the Admin Portal
- ✅
options.useSavedCredentialToLogin: trueandoptions.allowInteraction: trueon 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
Updated 3 days ago