Use the GET /api/v1/selection endpoint to get a selection from the cardholder.
The MultiOption form is used to get one of several options from the cardholder. Each option specified in the options query parameter will be shown as a button on the PIN pad.
Options should be pipe delimited. For example, to show three buttons labeled one, two, and three, set the options query parameter to one|two|three. The MultiOption
form accepts a general text argument which is used as the prompt text for the form. It also accepts a multiLineText argument, which is used to send in individual lines of text to be
displayed on a PIN pad that supports multi-line display. Lines of text should be separated by a pipe (|).
NOTE: A request with an empty or no text parameter will display a blank screen on the PIN pad.
If multiLineText is sent to a PIN pad that does not support multi-line, triPOS will prefer the text parameter without error.
If multiLineText is empty, or all lines sent in the multiLineText parameter are empty, triPOS will prefer the text parameter without error.
To intentionally leave a blank line on the PIN pad, send a space character as the text.
If multiLineText contains more lines than the PIN pad can display, or more characters per line than the PIN pad can display, then triPOS will truncate the input before displaying and will not return any error messages.
Currently, only Vx805 and Vx690 PIN pads running XPI v12 or higher are able to support multi-line display. The multiline display option can be replicated with the Verifone Mx915/925 PIN pads in triPOS by using the “\n” Line Feed character in the appropriate spots when using the “text” parameter. The Line Feed character is URL-encoded to “%0A”. Please note the number of characters displayed may differ among PIN pads
Example MultiOption request:
GET http://localhost:8080/api/v1/selection/1?form=MultiOption&text=Please%20choose%20an%20option&options=one|two|three
GET http://localhost:8080/api/v1/selection/1?form=MultiOption&multiLineText=line1|line2|line3&options=one|two|three
Like the MultiOption form, the MultiOptionTextArea form is used to get one of several options from the cardholder. It handles the options to display on the PIN pad in the same manner but allows the additional arguments of
header, subHeader, and text which can be used to display details explaining the selection options. The header and subHeader arguments are displayed at the top
of the form with the header above the subHeader.The text argument can be used to display text in a scrollable text area to allow for information that may be displayed in paragraph form.
Note: Currently only the Verifone Mx915 and Mx925 are supported.
Example MultiOptionTextArea request:
GET http://localhost:8080/api/v1/selection/1?form=MultiOptionTextArea&header=Header&subHeader=Subheader&text=detailed%20text%20line%201%0Adetailed%20text%20line%202&options=one|two|three
A maximum of 6 buttons is displayed on the screen. No limit is enforced on the characters to be displayed on a button; however, 6 characters is optimal. No error is returned when more than 6 options are sent in the request.
The YesNoTextArea form is used to get a Yes or No selection from the cardholder. If the cardholder chooses No, the returned selectionIndex will be 0. If the cardholder
chooses Yes, the returned selectionIndex will be 1. The YesNoTextArea form includes a header, sub-header, and a text area for detailed text. The text
area text is set with the text query parameter. Multiple lines may be separated with a newline character (\n), which URL encoded will
be represented by %0A.
Note: Ingenico devices do not support the newline character.
Example YesNoTextArea request:
GET http://localhost:8080/api/v1/selection/1?form=YesNoTextArea&header=Header&subHeader=Subheader&text=detailed%20text%20line%201%0Adetailed%20text%20line%202
A call to the selection endpoint form is typically followed by a transaction (eg. a sale) or a call to the idle endpoint.