Device Interaction/requestInput

Request Input from Cardholder

Prompt the cardholder for text, a selection, or a rating.

POST/v1/device/input

Ask the cardholder (or operator) for input using the terminal screen. Supports text, numeric, email, phone, selection lists, yes/no prompts, and star ratings. The call blocks until the user responds, cancels, or the timeout is reached — perfect for capturing emails for digital receipts, dine-in vs takeaway choices, or post-payment NPS prompts.

Request body

application/json

promptstringrequired

Prompt text displayed to the user (max 100 chars).

Example: "Enter your email for receipt"

inputTypeenumrequired

Type of input to request.

TEXTNUMERICEMAILPHONESELECTIONYES_NORATING

optionsarray

Options for SELECTION input type.

minLengthinteger

Minimum input length (TEXT/NUMERIC/EMAIL/PHONE).

maxLengthinteger

Maximum input length (TEXT/NUMERIC/EMAIL/PHONE).

timeoutMsinteger

Timeout in milliseconds (1000–120000).

Example: 30000

Response

application/json

valuestringnullable

The user's input. Null if cancelled or timed out.

cancelledbooleanrequired

User explicitly cancelled.

Example: false

timedOutbooleanrequired

Input timed out.

Example: false

commerce-api/openapi.yaml · requestInput

curl http://terminal:8443/v1/device/input \ -H "X-Api-Key: $ATLAS_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"prompt": "Enter your email for receipt","inputType": "EMAIL","timeoutMs": 30000}'