Device REST API: prompts and displays
Eight v5 operations for signatures, yes/no decisions, menu selections, QR display, and their lifecycle.
Environment and authentication
Base URL for every operation on this page: https://sandbox.nmi.com/api/v5. Send the private key directly as the Authorization header value, without a Bearer prefix. JSON requests use Content-Type: application/json. Keep credentials on your backend and select the merchant and device through your own authorized session. These paths are v5; do not substitute v2 camelCase fields or Classic security_key request bodies. Authorization: YOUR_SANDBOX_PRIVATE_KEY Content-Type: application/json Examples here describe sandbox request shapes only. They do not create a device, prompt a customer, or move money.
Signature — POST /devices/{device_id}/prompt/sign
device_id is required. Body header is a required string, maximum 100 characters. A 200 response creates the prompt request; it does not mean the customer has signed. Other documented responses: 400, 401, 404. Parameter Type / requirement Meaning or constraint header required string; ≤100 Device heading; must match the documented character pattern. ^[a-zA-Z0-9.,?!&\/#'-= ]{0,100}$
Signature status — GET /devices/{device_id}/prompt/sign/{reference}
Both path values are required strings. reference comes from the initial signature prompt response. HTTP 200 can describe a prompt still in progress or completed with a signature. Error responses are 400, 401, 404 and 500.
Yes/no — POST /devices/{device_id}/prompt/yes-no
Requires device_id. The body requires header and message: each is a string no longer than 100 characters and uses the same character pattern shown above. HTTP 200 creates the request; 400, 401 and 404 describe failures. { "header": "Confirm selection", "message": "Is this your order?" }
Yes/no status — GET /devices/{device_id}/prompt/yes-no/{reference}
Required device_id and reference are strings. Use the reference returned by the matching yes/no request. HTTP 200 includes in-progress, completed and cancelled outcomes; error responses are 400, 401, 404 and 500. A completed answer is not an approved payment.
Menu — POST /devices/{device_id}/prompt/menu
Requires device_id. Body header is required and limited to 24 characters. options is a required array containing 2–20 strings. HTTP 200 creates the request; documented failures are 400, 401 and 404. ^[a-zA-Z0-9.,?!\/#&'-= ]{0,24}$ Parameter Type / requirement Meaning or constraint header required string; ≤24 Short menu heading. options required string array; 2–20 items Choices to display; the reviewed page does not specify per-option length.
Menu status — GET /devices/{device_id}/prompt/menu/{reference}
Requires string device_id and reference from the initial menu request. HTTP 200 can describe in-progress interaction or completion with a selection. Error responses: 400, 401, 404, 500.
QR display — POST /devices/{device_id}/display/qr-code
Requires device_id. HTTP 200 means the display request succeeded; 400, 401 and 404 cover failures. Parameter Type / requirement Meaning or constraint header required string; ≤27 Same signature heading pattern, with length bound 27. qr_data required string; ≤1500 Data encoded into the displayed QR code. user_cancelled_allowed optional boolean; default false Whether the customer may cancel the display. { "header": "Order details", "qr_data": "https://example.com/order/demo", "user_cancelled_allowed": true }
Cancel display — DELETE /devices/{device_id}/display
Requires string device_id. Cancels the active display, including a displayed QR code. HTTP 200 is success; errors are 401 and 404. This operation is separate from cancellation of an asynchronous payment request.
Persist the correct reference
Prompt responses require object="request", id and status. Use id as the reference for the matching prompt status route. The status enum is in_progress, completed, cancelled, cancelledAtTerminal, cancelledByApi, cancelledByTimeout, poiDeviceInUse, poiDeviceDisconnected, or terminatedBadCardRead. A completed yes/no or menu interaction exposes result; a completed signature interaction exposes Base64 signature and signature_format. Recommended application state: persist merchant, device, prompt kind and reference together; never treat prompt completion as payment approval.
Detailed local operation contracts
Expand the corresponding local contract for full request and response structures, including nested fields. These contracts preserve the v5 operation boundary. prompt device sign v5 get device prompt sign status v5 prompt device yes no v5 get device prompt yes no status v5 prompt device menu v5 get device prompt menu status v5 display device qr code v5 cancel device display v5