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 |