On This Page
FILTER BY TAG

Custom Screens

Use this information to send a custom screen request in Local mode. This feature enables you to show one or more customized screens on the payment terminal. Custom screen can show informational text, collect text input, or capture a digital signature.

Endpoints

The endpoint is the same for the test and production environments.
Test:
wss://{terminal IP address:port number}/
Production:
wss://{terminal IP address:port number}/

Required Fields for Custom Screens

type
Set this field to
CustomScreenRequest
.
screens
Set this field to a list of one or more screen objects. Each screen must include a
screenType
 field to identify the type of custom screens to show on the payment terminal.

Required Fields for Custom Screens by Screen Type

Use these fields to define the required content for each custom screen in the
screens
 field. Each screen in this field must include a
screenType
 field that identifies the type of custom screen to show on the payment terminal. The
screens
 field supports these
screenType
 values:
textDisplay
,
textInput
, and
signatureCapture
.

textDisplay
 Screen

screens[n].screenType
Set this field to
textDisplay
.
screens[n].title
Set this field to the screen title. The title cannot exceed 20 characters.

textInput
 Screen

screens[n].screenType
Set this field to
textInput
.
screens[n].title
Set this field to the screen title. The title cannot exceed 20 characters.
screens[n].textInputs
Set this field to a list of one or more text input fields.
screens[n].textInputs[n].textInputLabel
Set this field to the label for the input field. The label cannot exceed 25 characters.
screens[n].textInputs[n].textInputConfig.textInputType
Set this field to the type of input to accept. Supported values are
NUMERIC
,
ALPHANUMERIC
,
EMAIL
, and
PHONE
.

signatureCapture
 Screen

screens[n].screenType
Set this field to
signatureCapture
.
screens[n].title
Set this field to the screen title. The title cannot exceed 20 characters.

Optional Fields for Custom Screens

Use these fields to define optional content and formatting for custom screens in the
screens
 field. Optional fields are available for all screen types, with additional optional fields supported for
textDisplay
 and
textInput
 screens.
IMPORTANT
If you do not specify the value for an optional field, the default value is used.

Optional Fields Available on All Screen Types

screens[n].description
Set this field to a descriptive message displayed below the title.
screens[n].isSkippable
Set this field to
true
 to allow the cardholder to skip the screen. The default value is
false
.

textDisplay
 Screen Optional Fields

screens[n].toggles
Set this field to a list of toggle items for the cardholder to accept or decline.
screens[n].toggles[n].label
Set this field to the label displayed next to the toggle. The label cannot exceed 40 characters.
screens[n].toggles[n].required
Set this field to
true
 to require the cardholder to enable the toggle before proceeding. The default value is
false
.

textInput
 Screen Optional Fields

screens[n].textInputs[n].textInputHint
Set this field to placeholder hint text displayed inside the input field.
screens[n].textInputs[n].textInputConfig.masked
Set this field to
true
 to mask the input characters as the cardholder types. The default value is
false
.
screens[n].textInputs[n].textInputConfig.length.min
Set this field to the minimum number of characters required. Must be greater than zero.
screens[n].textInputs[n].textInputConfig.length.max
Set this field to the maximum number of characters allowed. Must be greater than zero and not be less than the defined minimum characters.
screens[n].textInputs[n].textInputConfig.patternConfig.pattern
Set this field to a regular expression that the input value must match.
screens[n].textInputs[n].textInputConfig.patternConfig.patternError
Set this field to the error message displayed when the input does not match the pattern.
screens[n].toggles
Set this field to a list of toggle items for the cardholder to accept or decline.
screens[n].toggles[n].label
Set this field to the label displayed next to the toggle. The label cannot exceed 40 characters.
screens[n].toggles[n].required
Set this field to
true
 to require the cardholder to enable the toggle before proceeding. The default value is
false
.

REST Example: Custom Screens

Request
{
    "type": "CustomScreenRequest",
    "screens": [
        {
            "screenType": "signatureCapture",
            "title": "Confirm Receipt",
            "description": "I certify that I am the authorized representative to receive these goods...",
            "isSkippable": false
        },
        {
            "screenType": "textDisplay",
            "title": "Liability Waiver",
            "description": "By proceeding, you acknowledge inspection of goods...",
            "isSkippable": false,
            "toggles": [
                {
                    "label": "I accept the terms",
                    "required": true
                }
            ]
        },
        {
            "screenType": "textInput",
            "title": "Purchase Order (PO)",
            "description": "Please enter the authorized Purchase Order (PO) number...",
            "isSkippable": false,
            "textInputs": [
                {
                    "textInputLabel": "Authorized PO Number",
                    "textInputHint": "PO518736",
                    "textInputConfig": {
                        "textInputType": "ALPHANUMERIC",
                        "masked": true,
                        "length": {
                            "min": 5,
                            "max": 10
                        },
                        "patternConfig": {
                            "pattern": "^[a-zA-Z0-9]*$",
                            "patternError": "Only letters and numbers allowed"
                        }
                    }
                }
            ],
            "toggles": [
                {
                    "label": "I accept the terms",
                    "required": true
                }
            ]
        }
    ]
}
Mid-Transaction Status Updates
During the operation, you might receive one or more update responses indicating the current status of the operation. You can choose to display these updates on your point-of-sale (POS) system. 
{
      "type": "OperationStatusResponse",
      "message": "Status update to display."
}
Response to a Successful Request
{
    "type": "CustomScreenResponse",
    "message": "Data capture successful",
    "customScreenDetails": {
        "status": "COMPLETED",
        "screens": [
            {
                "screenType": "signatureCapture",
                "title": "Confirm Receipt",
                "signatureData": "iVBORw0KGgoAAAANSUhEUg....",
                "skipped": false
            },
            {
                "screenType": "textDisplay",
                "title": "Liability Waiver",
                "toggles": [
                    {
                        "label": "I accept the terms",
                        "value": true
                    }
                ],
                "skipped": false
            },
            {
                "screenType": "textInput",
                "title": "Purchase Order (PO)",
                "inputs": [
                    {
                        "label": "Authorized PO Number",
                        "value": "PO518736"
                    }
                ],
                "toggles": [
                    {
                        "label": "I accept the terms",
                        "value": true
                    }
                ],
                "skipped": false
            }
        ]
    }
}
Response to an Unsuccessful Request
When the request is unsuccessful, you receive an error response with details.
{
          "type": "ErrorResponse",
          "message": "Error message to display.",
          "developerDescription": "Detailed description of error."
}
RELATED TO THIS PAGE