Custom Screens {#ttp-sis-pymnt-svcs-cloud-custom-screens-intro} =============================================================== Use this information to send a custom screen request in Cloud 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 --------- **Test:** `POST https://terminalstest.cybersource.com/v1/cloud/transactions` **Production:** `POST https://terminals.cybersource.com/v1/cloud/transactions` Required Fields for Custom Screens {#ttp-sis-pymnt-svcs-cloud-custom-screens-reqfields} ======================================================================================= serialNumber : Set this field to the serial number of the terminal. request.type : Set this field to `CustomScreenRequest`. request.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 {#ttp-sis-pymnt-svcs-cloud-custom-screens-type-reqfields} =========================================================================================================== Use these fields to define the required content for each custom screen in the request.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 request.screens field supports these screenType values: `textDisplay`, `textInput`, and `signatureCapture`. textDisplay Screen ------------------ request.screens\[n\].screenType : Set this field to `textDisplay`. request.screens\[n\].title : Set this field to the screen title. The title cannot exceed 20 characters. textInput Screen ---------------- request.screens\[n\].screenType : Set this field to `textInput`. request.screens\[n\].title : Set this field to the screen title. The title cannot exceed 20 characters. request.screens\[n\].textInputs : Set this field to a list of one or more text input fields. request.screens\[n\].textInputs\[n\].textInputLabel : Set this field to the label for the input field. The label cannot exceed 25 characters. request.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 ----------------------- request.screens\[n\].screenType : Set this field to `signatureCapture`. request.screens\[n\].title : Set this field to the screen title. The title cannot exceed 20 characters. Optional Fields for Custom Screens {#ttp-sis-pymnt-svcs-cloud-custom-screens-optfields} ======================================================================================= 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 --------------------------------------------- request.screens\[n\].description : Set this field to a descriptive message displayed below the title. request.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 ---------------------------------- request.screens\[n\].toggles : Set this field to a list of toggle items for the cardholder to accept or decline. request.screens\[n\].toggles\[n\].label : Set this field to the label displayed next to the toggle. The label cannot exceed 40 characters. request.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 -------------------------------- request.screens\[n\].textInputs\[n\].textInputHint : Set this field to placeholder hint text displayed inside the input field. request.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`. request.screens\[n\].textInputs\[n\].textInputConfig.length.min : Set this field to the minimum number of characters required. Must be greater than zero. request.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. request.screens\[n\].textInputs\[n\].textInputConfig.patternConfig.pattern : Set this field to a regular expression that the input value must match. request.screens\[n\].textInputs\[n\].textInputConfig.patternConfig.patternError : Set this field to the error message displayed when the input does not match the pattern. request.screens\[n\].toggles : Set this field to a list of toggle items for the cardholder to accept or decline. request.screens\[n\].toggles\[n\].label : Set this field to the label displayed next to the toggle. The label cannot exceed 40 characters. request.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 {#ttp-sis-pymnt-svcs-cloud-custom-screens-ex-rest} =============================================================================== Request ``` { "serialNumber": "1850000000", "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 } ] } ] } } ``` 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." } ```