Terminals Endpoint

Capabilities

Methods	POST, PUT, GET, DELETE
Filters	tip_enable, terminal_cvm_id, terminal_manufacturer_id
Expands	terminal_application, location, created_user

For GET requests:

Filters can be used to search for Terminals by including the columns you want to filter on as URL parameters.
i.e. /v2/terminals?field=value&field2=value2
Expands can be used to include information related to the record being retrieved.
i.e. /v2/terminals/{id}?expand=location,created_user
Note: Please visit the Expands (Related Records) page for more details about using Expands.

Fields

Name	Type/Format	Length	Default	Comments
active	boolean	1	1	Active
cashback_enable	boolean	1		Required. Indiicates if terminal is Cashback enabled
created_ts	integer	10	System Generated	Created time stamp
created_user_id	string		System Generated
communication_type	string			Optional. Valid values are 'http', 'tcp/ip', 'usb/serial'
debit	boolean	1		Required. Indicates if debit is enabled
default_checkin	string	20		yyyy-mm-dd. Default checkin date
default_checkout	string	20		yyyy-mm-dd. Default checkout date
default_room_number	string	12		Default room number
default_room_rate	string	100		Default room rate
emv	boolean	1		Required. Indicats if EMV is enabled.
header_line_1	string	32		Receipt header line 1
header_line_2	string	32		Receipt header line 2
header_line_3	string	32		Receipt header line 3
header_line_4	string	32		Receipt header line 4
header_line_5	string	32		Receipt header line 5
id	string	36	System Generated	ID
is_provisioned	boolean	1		Indicates if terminal is provisioned
last_registration_ts	integer	10		Last Registration time stamp
local_ip_address	string	15		Terminal Local IP Address
location_id	string	36		Location ID where terminal will be used
mac_address	string	16		Terminal MAC Address
modified_ts	integer	10	System Generated	Modified time stamp
modified_user_id	string		System Generated
port	integer	5	10009	Terminal Port
print_enable	boolean	1		Required. Indicates if terminal is print enabled
serial_number	string	36		Terminal Serial Number
sig_capture_enable	boolean	1		Required. Indicates if terminal is signature capture enabled
terminal_api_id	string	64		Optional. Must be unique per location. This field can be used to correlate Terminals in our system to data within an outside software integration.
terminal_cvm_id	string			Terminal CMV ID. Required for terminals with terminal cvms
terminal_number	string	36		Terminal Number
terminal_timeouts	JSON			A JSON of timeout fields specific to Ingenico devices.
tip_enable	boolean	1		Indicates if terminal is tip enabled
tip_percents	JSON			A JSON of tip percents the JSON MUST contain only these three fields: percent_1, percent_2, percent_3 each field can only contain a value from 0 to 99, if 1 field is NULL, all fields must be null
title	string	64		Title
trailer_line_1	string	32		Receipt footer line 1
trailer_line_2	string	32		Receipt footer line 2
trailer_line_3	string	32		Receipt footer line 3
trailer_line_4	string	32		Receipt footer line 4
trailer_line_5	string	32		Receipt footer line 5
validated_decryption	boolean	1		Only for INGENICO Devices

Endpoint Actions

Create Record

POST /v2/terminals

{
    "terminal": {
        "location_id": "{{location_id}}",
        "terminal_application_id": "{{terminalapplication_id}}",
        "serial_number": "{{serial_number}}",
        "terminal_manufacturer_id": "1",
        "terminal_timeouts": {
            "status_display_time": 12,
            "transaction_timeout": 17,
            "overall_timeout": 125,
            "card_entry_timeout": 47,
            "pin_entry_timeout": 40,
            "tip_cashback_timeout": 25,
            "signature_input_timeout": 35,
            "signature_submit_timeout": 38,
            "device_terms_prompt_timeout": 30
        },
        "tip_percents":{
            "percent_1":0,
            "percent_2":2,
            "percent_3":99
        }
    }
}

{
    "terminal": {
        "id": "{terminal_id}",
        "location_id": "{location_id}",
        "active": 1,
        "local_ip_address": null,
        "port": null,
        "last_registration_ts": null,
        "serial_number": "Tpg7zmq0bm7h",
        "title": null,
        "mac_address": null,
        "terminal_number": null,
        "created_ts": 1542233880,
        "modified_ts": 1542233880,
        "debit": false,
        "emv": false,
        "header_line_1": null,
        "header_line_2": null,
        "header_line_3": null,
        "header_line_4": null,
        "header_line_5": null,
        "trailer_line_1": null,
        "trailer_line_2": null,
        "trailer_line_3": null,
        "trailer_line_4": null,
        "trailer_line_5": null,
        "communication_type": null,
        "is_provisioned": 0,
        "default_checkin": null,
        "default_checkout": null,
        "default_room_rate": null,
        "default_room_number": null,
        "terminal_application_id": "{terminal_application_id}",
        "terminal_manufacturer_id": "1",
        "terminal_cvm_id": null,
        "tip_enable": false,
        "cashback_enable": 0,
        "print_enable": 0,
        "sig_capture_enable": 0,
        "created_user_id": "{created_user_id}",
        "modified_user_id": "{modified_user_id}",
        "terminal_timeouts": {
            "status_display_time": 12,
            "transaction_timeout": 17,
            "overall_timeout": 125,
            "card_entry_timeout": 47,
            "pin_entry_timeout": 40,
            "tip_cashback_timeout": 25,
            "signature_input_timeout": 35,
            "signature_submit_timeout": 38,
            "device_terms_prompt_timeout": 30
        },
        "tip_percents":{
            "percent_1":0,
            "percent_2":2,
            "percent_3":99
        }
        "_links": {
            "self": {
                "href": "https://sandbox.domain.com/v2/terminals/{id}"
            }
        }
    }
}

Update Record

PUT /v2/terminals/{id}

{
    "terminal": {
        "active": 0
    }
}

{
    "terminal": {
        "id": "{terminal_id}",
        "location_id": "{location_id}",
        "active": 0,
        "local_ip_address": null,
        "port": null,
        "last_registration_ts": null,
        "serial_number": "Tpg7zmq0bm7h",
        "title": null,
        "mac_address": null,
        "terminal_number": null,
        "created_ts": 1542233880,
        "modified_ts": 1542233880,
        "debit": false,
        "emv": false,
        "header_line_1": null,
        "header_line_2": null,
        "header_line_3": null,
        "header_line_4": null,
        "header_line_5": null,
        "trailer_line_1": null,
        "trailer_line_2": null,
        "trailer_line_3": null,
        "trailer_line_4": null,
        "trailer_line_5": null,
        "communication_type": null,
        "is_provisioned": 0,
        "default_checkin": null,
        "default_checkout": null,
        "default_room_rate": null,
        "default_room_number": null,
        "terminal_application_id": "{terminal_application_id}",
        "terminal_manufacturer_id": "1",
        "terminal_cvm_id": null,
        "tip_enable": false,
        "cashback_enable": 0,
        "print_enable": 0,
        "sig_capture_enable": 0,
        "created_user_id": "{created_user_id}",
        "modified_user_id": "{modified_user_id}",
        "terminal_timeouts": {
            "status_display_time": 12,
            "transaction_timeout": 17,
            "overall_timeout": 125,
            "card_entry_timeout": 47,
            "pin_entry_timeout": 40,
            "tip_cashback_timeout": 25,
            "signature_input_timeout": 35,
            "signature_submit_timeout": 38,
            "device_terms_prompt_timeout": 30
        },
        "tip_percents": {
            "percent_1": 0,
            "percent_2": 2,
            "percent_3": 99
        }
        "_links": {
            "self": {
                "href": "https://sandbox.domain.com/v2/terminals/{id}"
            }
        }
    }
}

View Single Record

GET /v2/terminals/{id}

{
    // Empty Payload - Nothing Needed Here
}

{
    "terminal": {
        "id": "{id}",
        "active": 1,
        "created_ts": 1422040669,
        "last_registration_ts": 1422040669,
        "local_ip_address": "0.0.0.0",
        "location_id": "{location_id}",
        "mac_address": "aabbccddeeff",
        "modified_ts": 1422040669,
        "port": 10009,
        "serial_number": "abcdef",
        "terminal_number": "abcdef",
        "title": "Test Terminal",
        "_links": {
            "self": {
                "href": "https://develop.domain.com/v2/terminals/{id}"
            }
        }
    }
}

View Record List

GET /v2/terminals

{
    // Empty Payload - Nothing Needed Here
}

{
    "terminals": [
        {
            "id": "{terminal_id}",
            "location_id": "{location_id}",
            "active": 1,
            "local_ip_address": null,
            "port": null,
            "last_registration_ts": null,
            "serial_number": "Tpg7zmq0bm7h",
            "title": null,
            "mac_address": null,
            "terminal_number": null,
            "created_ts": 1542233880,
            "modified_ts": 1542233880,
            "debit": false,
            "emv": false,
            "header_line_1": null,
            "header_line_2": null,
            "header_line_3": null,
            "header_line_4": null,
            "header_line_5": null,
            "trailer_line_1": null,
            "trailer_line_2": null,
            "trailer_line_3": null,
            "trailer_line_4": null,
            "trailer_line_5": null,
            "communication_type": null,
            "is_provisioned": 0,
            "default_checkin": null,
            "default_checkout": null,
            "default_room_rate": null,
            "default_room_number": null,
            "terminal_application_id": "{terminal_application_id}",
            "terminal_manufacturer_id": "1",
            "terminal_cvm_id": null,
            "tip_enable": false,
            "cashback_enable": 0,
            "print_enable": 0,
            "sig_capture_enable": 0,
            "created_user_id": "{created_user_id}",
            "modified_user_id": "{modified_user_id}",
            "terminal_timeouts": {
                "status_display_time": 12,
                "transaction_timeout": 17,
                "overall_timeout": 125,
                "card_entry_timeout": 47,
                "pin_entry_timeout": 40,
                "tip_cashback_timeout": 25,
                "signature_input_timeout": 35,
                "signature_submit_timeout": 38,
                "device_terms_prompt_timeout": 30
            },
            "tip_percents":{
                "percent_1":0,
                "percent_2":2,
                "percent_3":99
            }
            "_links": {
                "self": {
                    "href": "https://sandbox.domain.com/v2/terminals/{id}"
                }
            }
        }
        ... // Other Terminals Here
    ],
    "meta": {
        "pagination": {
            "links": {
                "self": {
                    "href": "https://develop.domain.com/v2/terminals?location_id={id}&page_size=3&page=1"
                }
            },
            "totalCount": 2,
            "pageCount": 1,
            "currentPage": 0,
            "perPage": 3
        },
        "sort": {
            "attributes": {
                "id": "desc"
            }
        }
    }
}

Ingenico Timeouts

The following table outlines some configurable timeout values that can be used to customize the experience at the terminal for the cardholder.

These timeouts are specific to Ingenico devices only.

These values are defaulted in the system, if you would like the default values changed on production terminals you will need to contact customer service.

Note: Please visit the test data page to see additional transaction amounts that will aid in testing.

Name	Default	Min	Max	Description	Validation message on timeout
card_entry_timeout	120	20	120	How long to wait for input from cardholder.	Card Entry Timeout
device_terms_prompt_timeout	60	5	300	How long the terms will be displayed on the device.	Timeout waiting for Customer
overall_timeout	300	30	300	How long to wait for response from /v2/routertransactions endpoint.	Overall Request Timeout
pin_entry_timeout	30	20	50	How long to wait for pin entry by cardholder.	Pin Entry Timeout
signature_input_timeout	10	10	50	How long to wait for first "touch" to signature.	Signature Input Timeout
signature_submit_timeout	30	20	50	How long to wait for signature to be submitted.	Signature Storage Timeout
status_display_time	7	1	30	How long the approve/decline status message stays on screen.	N/A - Not actually a "timeout". This is a time to display the status on the screen.
tip_cashback_timeout	30	20	50	How long to wait for input on a tip or cashback screen.	Tip/Cashback Timeout
transaction_timeout	10	10	20	How long to wait for response from the processor.	Transaction Timeout