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
id	string	36	System Generated	ID
active	boolean	1	1	Active
created_ts	integer	10	System Generated	Created time stamp
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
port	integer	5	10009	Terminal Port
serial_number	string	36		Terminal Serial Number
terminal_number	string	36		Terminal Number
terminal_timeouts	JSON			A JSON of timeout fields specific to Ingenico devices.
title	string	64		Title
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

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