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