Send Interactive Inputs

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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

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 both useSaveCredentials: true and allowInteraction: 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:

ApproachHow it worksUse this endpoint?
CartAI-hosted screenShow the customer the URL in requiredInputs[].value. The hosted screen collects the input and submits it for you.No
Your own UIBuild 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.

⚠️

OTPs expire quickly. Send the code as soon as the customer enters it.


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

ParameterLocationTypeRequiredDescription
taskIdPathstring (UUID)✅ YesID of the checkout task that is waiting for input.
intentPathstring✅ YesType of input being sent. Supported: mfa.
x-api-keyHeaderstring✅ YesYour CartAI API key.

Request body

FieldTypeRequiredDescription
otpstring✅ 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

FieldTypeDescription
statusstring"success" when the input was accepted.
messagestringHuman-readable result message.
tasks[].taskIdstring (UUID)The checkout task the input was sent to.
tasks[].executionIdstring (UUID)The execution attempt that received the input.
tasks[].statusstringThe 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 StatusCauseWhat to do
201Input submitted successfullyKeep listening for checkout task webhooks to follow the task's progress
400intent isn't supported, otp is missing or the wrong length, or the body has extra fieldsUse mfa as the intent, send only otp, and check that it's 4–8 characters
403The task doesn't belong to the caller, or the task is past the stage where it accepts an OTPCheck that you're using the right API key and taskId. Only send input while the task is waiting for it
404The task wasn't foundCheck that the taskId is correct
409An OTP was already submitted for this taskDon't resend. Wait for the next webhook event
500Unexpected server errorRetry after a short delay; contact support if it persists
Path Params
uuid
required

ID of the checkout task that is waiting for input

string
enum
required

Type of input being sent. Supported: mfa

Allowed:
Body Params
string
required
length between 4 and 8

The OTP/MFA code, 4–8 characters. Spaces at either end are trimmed. No other fields are allowed. Required when intent is mfa.

Headers
string
required
Responses

400

intent isn't supported, otp is missing or the wrong length, or the body has extra fields

403

The task doesn't belong to the caller, or the task is past the stage where it accepts an OTP

404

The task wasn't found

409

An OTP was already submitted for this task

500

Unexpected server error

Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json