Standalone Device Inputs

Start a standalone device input

It is possible to perform a standalone signature capture on a POI Device outside of a normal transaction flow.

Device support

Standalone device inputs are available on devices connected to the Customer-Present Cloud API. Not every device supports every action — the supported devices are listed under each action below, and summarised in Device support summary.

Standalone device inputs are not supported on Ingenico RBA devices (iPP320 and iSC250).

Querying the result of a standalone device input is not device-specific — the query endpoint polls the gateway rather than the device. If you request an action that the target device does not support, the query returns a status of unsupported_device.

Headers

Every API request must be authenticated using HTTP Bearer Authentication header and include a Content-Type header.

Authorization: Bearer {MERCHANT_API_KEY}
Content-Type: application/json

Signature

This allows for the capture of a customer’s electronic signature. This action is supported by the following devices: Lane 5000, Lane 7000, Miura M021.

Request:

GET https://secure.nmi.com/api/v2/devices/sign/:poiDeviceId

Example Request

curl --request GET \
--header "Authorization: Bearer {MERCHANT_API_KEY}" \
"https://secure.nmi.com/api/v2/devices/sign/d352da6e-8772-4433-92f6-a77c4926fd80"

Example response

{
    "async_status_guid": "118d6276-dfd4-4613-acfc-75d22bcdd189",
    "status": "in_progress"
}

Yes/No Prompt

This allows for the capture of a customer’s answer to a yes/no question with an on-screen header and optional message. This action is supported by the following devices: Lane 3000, Lane 3600, Lane 5000, Lane 7000, Link 2500, Link 2500LE, Miura M020, Miura M021.

Request:

GET https://secure.nmi.com/api/v2/devices/yesno/:poiDeviceId

Example request

curl --request GET \
--header "Authorization: Bearer {MERCHANT_API_KEY}" \
"https://secure.nmi.com/api/v2/devices/yesno/d352da6e-8772-4433-92f6-a77c4926fd80"

Example response

{
    "async_status_guid": "118d6276-dfd4-4613-acfc-75d22bcdd189",
    "status": "in_progress"
}

Multiple Choice Prompt

This allows for the capture of a customer’s answer to a multiple choice question with an on-screen header and options. This action is supported by the following devices: Lane 3000, Lane 3600, Lane 5000, Lane 7000, Link 2500, Link 2500LE, Miura M020, Miura M021.

Request:

GET https://secure.nmi.com/api/v2/devices/menuselection/:poiDeviceId

Example request

curl --request GET \
--header "Authorization: Bearer {MERCHANT_API_KEY}" \
--header "Content-Type: application/json" \
-d '{"header": "Question", "options": ["opt1", "opt2", "opt3"]}' \
"https://secure.nmi.com/api/v2/devices/menuselection/d352da6e-8772-4433-92f6-a77c4926fd80"

Example response

{
    "async_status_guid": "118d6276-dfd4-4613-acfc-75d22bcdd189",
    "status": "in_progress"
}

Query a standalone device input

In order to query the result of a standalone device input, you will need to use this endpoint to determine whether a customer’s interection with the POI device has completed or not and whether the request was successful. You will need to use the 'async_status_guid' value you received in the start standalone input response.

Endpoint

GET https://secure.nmi.com/api/asyncdevicestatus/:asyncStatusGuid

Headers

Every API request must be authenticated using HTTP Bearer Authentication header

Authorization: Bearer {MERCHANT_API_KEY}

Poll against an Asynchronous Device Input

Example Request without Response Method:

curl --request GET --header "Authorization: Bearer {MERCHANT_API_KEY}"
            "https://secure.nmi.com/api/asyncdevicestatus/70a6272c-4949-4515-956a-6e5ae4d5a10c"

Example Request with Asynchronous Response Method:

curl --request GET --header "Authorization: Bearer {MERCHANT_API_KEY}"
            "https://secure.nmi.com/api/asyncdevicestatus/70a6272c-4949-4515-956a-6e5ae4d5a10c?responseMethod=asynchronous"

Example Response without Response Method/with Asynchronous Response Method:

While the request is in progress, the responses will return with only the platform ID and status information.

{
    "reference": "be7e7e60-d3cc-4a67-a8a0-f89dbfb10257",
    "status": "in_progress"
}

Example Request with Synchronous Response Method:

curl --request GET --header "Authorization: Bearer {MERCHANT_API_KEY}"
            "https://secure.nmi.com/api/asyncdevicestatus/70a6272c-4949-4515-956a-6e5ae4d5a10c?responseMethod=synchronous"

When using a query parameter with the value of 'synchronous', the expected response would include the final request details with a status of complete, cancelled, timeout, error, unsupported_device or formatting_error:

Example Request with a successful signature response:

{
    "status": "complete",
    "signature": "iVBORw0 ...",
    "signature_format": "image/png"
}

The signature field will contain the signature image data encoded as a base64 string.The signature_format field contains the format of the image. This is currently only set to "image/png".

Example Request with a successful yes/no prompt response:

{
    "reference": "df5ea4b0-05d9-4ddd-ad7b-c1c63857fffd",
    "status": "complete",
    "result": true
}

The result field will indicate the customer's response to the yes/no question with a boolean value.

Example Request with a successful multiple choice prompt response:

{
    "reference": "df5ea4b0-05d9-4ddd-ad7b-c1c63857fffd",
    "status": "complete",
    "result": 2
}

The result field will indicate the customer's response to the multiple choice question with the number of the item in the list that was chosen. A result of 1 means that the first item in the list was chosen.

Error Handling

If successful, the response HTTP status code is 200 OK.

The following HTTP status codes will be returned in the event of various errors:

• 400 - No Platform ID or no API Key was sent in the request.
• 401 - An invalid API Key was sent in the request.

See Error Recovery Tips for common errors and ways to resolve them.

Display a QR code

Devices are capable of displaying a QR code on-screen with an optional header and the ability to specify whether the display of the QR code can be cancelled from the device. This action is supported by the following devices: Lane 3000, Lane 3600, Lane 5000, Lane 7000, Link 2500, Link 2500LE, Miura M020, Miura M021.

Headers

Every API request must be authenticated using HTTP Bearer Authentication header and include a Content-Type header.

Request:

POST https://secure.nmi.com/api/v2/devices/qrcode/:poiDeviceId

Example request

curl --request POST \
--header "Authorization: Bearer {MERCHANT_API_KEY}" \
"https://secure.nmi.com/api/v2/devices/qrcode/d352da6e-8772-4433-92f6-a77c4926fd80 \
--data '{
    "header": "Custom title",
    "qr_data": "My QR content",
    "user_cancelled_allowed": true
}"

Example response

{
    "success": true
}

Hide a QR code

If a QR code is on-screen, returns the device display to its idle screen. This action is supported by the following devices: Lane 3000, Lane 3600, Lane 5000, Lane 7000, Link 2500, Link 2500LE, Miura M020, Miura M021.

Request:

DELETE https://secure.nmi.com/api/v2/devices/display/:poiDeviceId

Example request

curl --request DELETE \
--header "Authorization: Bearer {MERCHANT_API_KEY}" \
"https://secure.nmi.com/api/v2/devices/qrcode/d352da6e-8772-4433-92f6-a77c4926fd80"

Example response

{
    "success": true
}

Device support summary

The table below summarises which devices support each standalone device input.