Sends input from the customer to a checkout task that is paused and waiting for it. Right now the only supported input is an MFA/OTP code.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
When to Use This Endpoint
Some merchants ask the shopper for extra input during checkout, such as a one-time password (OTP) sent by SMS or email. When a checkout task is created with allowInteraction: true, the agent pauses at that step. CartAI then sends a webhook event with a requiredInputs array describing what it needs.
Note: interactive inputs currently only work when the checkout task is created with bothuseSaveCredentials: trueandallowInteraction: true. If either flag is missing, the agent won't pause for input and this endpoint won't apply.
You can collect the input in either of two ways:
| Approach | How it works | Use this endpoint? |
|---|---|---|
| CartAI-hosted screen | Show the customer the URL in requiredInputs[].value. The hosted screen collects the input and submits it for you. | No |
| Your own UI | Build a form from requiredInputs[].inputSchema, collect the input in your app, and send it to CartAI. | ✅ Yes |
See Interactive Checkouts in Checkout Task Webhooks for the full requiredInputs format.
Authentication
Every request must include your API key in the request header.
x-api-key: YOUR_API_KEY_HERE- Always call this endpoint from your backend. Never expose your API key in client-side code.
Request
POST /checkout/{taskId}/{intent}
Path and header parameters
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
taskId | Path | string (UUID) | ✅ Yes | ID of the checkout task that is waiting for input. |
intent | Path | string | ✅ Yes | Type of input being sent. Supported: mfa. |
x-api-key | Header | string | ✅ Yes | Your CartAI API key. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
otp | string | ✅ Yes (for mfa) | The OTP/MFA code, 4–8 characters. Spaces at either end are trimmed. No other fields are allowed. |
{
"otp": "482913"
}Full Request Example
curl --location 'https://api.cartai.ai/checkout/0193f2a1-7c4e-7b2a-9d1f-3e5a6b7c8d90/mfa' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--header 'Content-Type: application/json' \
--data '{
"otp": "482913"
}'Response
A successful request returns HTTP 201 with the following body.
{
"status": "success",
"message": "OTP submitted.",
"tasks": [
{
"taskId": "0193f2a1-7c4e-7b2a-9d1f-3e5a6b7c8d90",
"executionId": "0193f2a1-8d5f-7c3b-8e2a-4f6b7c8d9e01",
"status": "mfa_received"
}
]
}Response Fields
| Field | Type | Description |
|---|---|---|
status | string | "success" when the input was accepted. |
message | string | Human-readable result message. |
tasks[].taskId | string (UUID) | The checkout task the input was sent to. |
tasks[].executionId | string (UUID) | The execution attempt that received the input. |
tasks[].status | string | The task's input status after the request (e.g. mfa_received). |
A 201 means CartAI has received the input and passed it to the agent. It doesn't mean the merchant accepted the code. Keep listening for checkout task webhooks to see whether the checkout continues or fails.
Example: Responding to an MFA Request
// 1. Webhook handler: the agent is asking for an OTP
app.post("/webhook", async (req, res) => {
res.status(200).json({ received: true }); // Always acknowledge first
const { tid, requiredInputs } = req.body;
const mfa = requiredInputs?.find((input) => input.intent === "mfa-request");
if (mfa) {
// Show your own OTP form, built from mfa.inputSchema
await promptCustomerForOtp(tid, mfa.inputSchema);
}
});
// 2. Your app collects the OTP from the customer and sends it to CartAI
async function submitOtp(taskId, otp) {
const res = await fetch(`https://api.cartai.ai/checkout/${taskId}/mfa`, {
method: "POST",
headers: {
"x-api-key": process.env.CARTAI_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ otp: otp.trim() }),
});
if (res.status === 409) {
// An OTP was already submitted for this task; don't resend
return;
}
if (!res.ok) {
throw new Error(`OTP submission failed with status ${res.status}`);
}
return res.json();
}Error Reference
| HTTP Status | Cause | What to do |
|---|---|---|
201 | Input submitted successfully | Keep listening for checkout task webhooks to follow the task's progress |
400 | intent isn't supported, otp is missing or the wrong length, or the body has extra fields | Use mfa as the intent, send only otp, and check that it's 4–8 characters |
403 | The task doesn't belong to the caller, or the task is past the stage where it accepts an OTP | Check that you're using the right API key and taskId. Only send input while the task is waiting for it |
404 | The task wasn't found | Check that the taskId is correct |
409 | An OTP was already submitted for this task | Don't resend. Wait for the next webhook event |
500 | Unexpected server error | Retry after a short delay; contact support if it persists |
400intent isn't supported, otp is missing or the wrong length, or the body has extra fields
403The task doesn't belong to the caller, or the task is past the stage where it accepts an OTP
404The task wasn't found
409An OTP was already submitted for this task
500Unexpected server error