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

 

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
        }
    }
}
{
    "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,
        "model": "s80",
        "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
        },
        "_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,
        "model": "s80",
        "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
        },
        "_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": "{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}"
                }
            }
        },
        ... // 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