Terminal Requests
Overview
Requests to the terminal require that the device has been setup in "server mode". This mode allows the device to act as its own server to handle directing requests and responses to the correct endpoint. When sending requests to the machine, the URL follows the format ws://{device_ip}/tsi/endpoint where the device_ip is the devices ip address and endpoint is the endpoint type being used.
Info
URL : ws://{device ip:50000}/tsi/v1/info
Terminal Info
Requests terminal info such as RAM, OS version, SDK version, TSI version etc. Full list of information provided back can be found in the response below.
Request
{
"request": {
"flow_id": "720372",
"resource": {
"type": "terminal_info"
}
}
}
Response
{
"event": {
"flow_id": "720372",
"resource": {
"results": [
{
"parameters": {
"Build Number:": "0028",
"Device Type:": "Move5000",
"Flash Available:": "370368512",
"Flash Total:": "449167360",
"Hardware Serial Number:": "220827303201181724276467",
"Manager Ver:": "44",
"OS Version:": "05",
"Package Name:": "BFN",
"Package Version:": "6.0.3",
"Power Shutdown Counter:": "172",
"RAM Available:": "384831488",
"RAM Total:": "518262784",
"Reboot Counter:": "448",
"SDK Version:": "14.04.01 PatchGH(b99)",
"TSI library version: ": "3.2.2",
"TSI version: ": "3.2.2",
"Uptime:": "445172"
},
"status": "receipt_information",
"transaction_date": "26/07/26",
"transaction_time": "10:26:59"
}
],
"status": "completed"
}
}
}
Config
URL : ws://{device ip:50000}/tsi/v1/config
Set time and date
Sets the date and time on the terminal. Structure of the request is as follows:
Date Format: YYMMDD
Time Format: HHMMSS
Request
{
"request": {
"flow_id": "118323",
"resource": {
"type": "set_date_time",
"date": "260726",
"time": "102001"
}s
}
}
Response
{
"event": {
"flow_id": "118323",
"resource": {
"results": [
{
"status": "approved"
}
],
"status": "completed"
}
}
}
Payment
URL : ws://{device ip:50000}/tsi/v1/payment
Sale
Request
{
"request": {
"flow_id": "277554",
"resource": {
"type": "sale",
"amount": 100
}
}
}
Response (EMV example)
{
"event": {
"flow_id": "926",
"resource": {
"results": [
{
"account_last4": "0045",
"aid_emv_parameters": [
{
"tac_default": "FC 50 BC A0 00",
"tac_denial": "00 00 00 00 00",
"tac_online": "FC 50 BC F8 00"
}
],
"authorization_no": "050142",
"batch_no": "4",
"card": {
"entry_mode": {
"code": "1",
"text": "insert"
},
"type": {
"code": "02",
"text": "mastercard"
}
},
"card_expiration": "1225",
"currency": "USD",
"customer_card_description": "MasterCard",
"customer_language": "0",
"customer_name": "MTIP08-2 MCD 13A",
"cvm_result": "0",
"emv": {
"aid": "A0000000041010",
"application_label": "MasterCard",
"data": {
"82": "58 00",
"5F2A": "08 40",
"5F34": "03",
"9A": "08/18/25",
"9F02": "$1.00",
"9F03": "$0.00",
"9F07": "FF00",
"9F0D": "FC 50 A0 00 00",
"9F0E": "00 00 00 00 00",
"9F0F": "F8 70 A4 98 00",
"9F12": "MasterCard",
"9F1A": "08 40",
"9F21": "09:18:17",
"9F26": "11 22 33 44 55 66 77 88",
"9F27": "40",
"9F34": "1E 03 00",
"9F36": "00 01",
"9F37": "4C7A9A11"
},
"tsi": "E800",
"tvr": "4200008000"
},
"host_response_isocode": "00",
"host_response_text": "APPROVED",
"host_transaction_reference": "000000051266",
"merchant_id": "xxxxxxxxx",
"receipt_information": {
"endorsement": [
"I AGREE TO PAY ABOVE TOTAL AMOUNT",
"IN ACCORDANCE WITH CARD ISSUER'S",
"AGREEMENT",
"(MERCHANT AGREEMENT IF CREDIT VOUCHER)",
"RETAIN THIS COPY FOR STATEMENT",
"VERIFICATION"
],
"footer": [
"Thank You",
"Please Come Again"
],
"header": [
"ASU Student Accounts 202",
"287 RIVERS ST",
"sdfasdfasdfas",
"855-278-5080"
]
},
"reference_no": "1",
"status": "approved",
"tac_default": "FC 50 BC A0 00",
"tac_denial": "00 00 00 00 00",
"tac_online": "FC 50 BC F8 00",
"terminal_id": "0000",
"total_amount": "100",
"transaction_amount": "100",
"transaction_date": "25/08/18",
"transaction_time": "09:19:10",
"type": "sale"
}
],
"status": "completed"
}
}
}
Refund
Request
{
"request": {
"flow_id": "576680",
"resource": {
"type": "refund",
"amount": 100
}
}
}
Response
{
"event": {
"flow_id": "79846",
"resource": {
"results": [
{
"account_last4": "0045",
"authorization_no": "++++++",
"batch_no": "4",
"card": {
"type": {
"code": "08",
"text": "other_credit"
}
},
"card_expiration": "1225",
"currency": "USD",
"cvm_result": "0",
"emv": {
"application_label": ""
},
"host_response_text": "REFUND",
"host_transaction_reference": "000000051326",
"merchant_id": "xxxxxxxxxxxx",
"receipt_information": {
"endorsement": [
"I AGREE TO PAY ABOVE TOTAL AMOUNT",
"IN ACCORDANCE WITH CARD ISSUER'S",
"AGREEMENT",
"(MERCHANT AGREEMENT IF CREDIT VOUCHER)",
"RETAIN THIS COPY FOR STATEMENT",
"VERIFICATION"
],
"footer": [
"Thank You",
"Please Come Again"
],
"header": [
"ASU Student Accounts 202",
"287 RIVERS ST",
"sdfasdfasdfas",
"855-278-5080"
]
},
"reference_no": "2",
"status": "approved",
"terminal_id": "0000",
"total_amount": "100",
"transaction_amount": "100",
"transaction_date": "25/08/18",
"transaction_time": "09:23:01",
"type": "refund"
}
],
"status": "completed"
}
}
}
Recall_last_transaction
Request
{
"request": {
"flow_id": "474643",
"resource": {
"type": "recall_last_transaction"
}
}
}
Response
{
"event": {
"flow_id": "474643",
"resource": {
"results": [
{
"account_last4": "0045",
"authorization_no": "++++++",
"batch_no": "4",
"card": {
"type": {
"code": "08",
"text": "other_credit"
}
},
"card_expiration": "1225",
"currency": "USD",
"host_response_text": "REFUND",
"host_transaction_reference": "000000051326",
"merchant_id": "220614986921",
"reference_no": "2",
"status": "approved",
"terminal_id": "0000",
"total_amount": "100",
"transaction_amount": "100",
"transaction_date": "25/08/18",
"transaction_time": "09:23:01",
"type": "refund"
}
],
"status": "completed"
}
}
}
Pre Authorization
Request
{
"request": {
"flow_id": "474643",
"resource": {
"type": "pre_auth",
"amount": "100"
}
}
}
Response
{
"event": {
"flow_id": "474643",
"resource": {
"results": [
{
"account_last4": "0045",
"aid_emv_parameters": [
{
"tac_default": "FC 50 BC A0 00",
"tac_denial": "00 00 00 00 00",
"tac_online": "FC 50 BC F8 00"
}
],
"authorization_no": "050263",
"batch_no": "4",
"card": {
"entry_mode": {
"code": "1",
"text": "insert"
},
"type": {
"code": "02",
"text": "mastercard"
}
},
"card_expiration": "1225",
"currency": "USD",
"customer_card_description": "MasterCard",
"customer_language": "0",
"customer_name": "MTIP08-2 MCD 13A",
"cvm_result": "0",
"emv": {
"aid": "A0000000041010",
"application_label": "MasterCard",
"data": {
"82": "58 00",
"5F2A": "08 40",
"5F34": "03",
"9A": "08/18/25",
"9F02": "$1.00",
"9F03": "$0.00",
"9F07": "FF00",
"9F0D": "FC 50 A0 00 00",
"9F0E": "00 00 00 00 00",
"9F0F": "F8 70 A4 98 00",
"9F12": "MasterCard",
"9F1A": "08 40",
"9F21": "09:33:17",
"9F26": "11 22 33 44 55 66 77 88",
"9F27": "40",
"9F34": "1E 03 00",
"9F36": "00 01",
"9F37": "866B87CC"
},
"tsi": "E800",
"tvr": "4200008000"
},
"host_response_isocode": "00",
"host_response_text": "APPROVED",
"host_transaction_reference": "000000051346",
"merchant_id": "220614986921",
"receipt_information": {
"endorsement": [
"I AGREE TO PAY ABOVE TOTAL AMOUNT",
"IN ACCORDANCE WITH CARD ISSUER'S",
"AGREEMENT",
"(MERCHANT AGREEMENT IF CREDIT VOUCHER)",
"RETAIN THIS COPY FOR STATEMENT",
"VERIFICATION"
],
"footer": [
"Thank You",
"Please Come Again"
],
"header": [
"ASU Student Accounts 202",
"287 RIVERS ST",
"sdfasdfasdfas",
"855-278-5080"
]
},
"reference_no": "300001",
"status": "approved",
"tac_default": "FC 50 BC A0 00",
"tac_denial": "00 00 00 00 00",
"tac_online": "FC 50 BC F8 00",
"terminal_id": "0000",
"total_amount": "100",
"transaction_amount": "100",
"transaction_date": "25/08/18",
"transaction_time": "09:33:32",
"type": "pre_auth"
}
],
"status": "completed"
}
}
}
Pre Authorization Completion
When the request is sent to the payment terminal, the device will display a menu to select the pre authorization to complete.
Request
{
"request": {
"flow_id": "474643",
"resource": {
"type": "pre_auth_completion",
"amount": "100"
}
}
}
Response
{
"event": {
"flow_id": "474643",
"resource": {
"results": [
{
"account_last4": "0045",
"aid_emv_parameters": [
null
],
"authorization_no": "050263",
"batch_no": "4",
"card": {
"entry_mode": {
"code": "1",
"text": "insert"
},
"type": {
"code": "02",
"text": "mastercard"
}
},
"card_expiration": "1225",
"currency": "USD",
"customer_card_description": "MasterCard",
"customer_language": "0",
"cvm_result": "0",
"emv": {
"aid": "A0000000041010",
"application_label": "MasterCard",
"data": {
"82": "58 00",
"5F34": "03",
"9A": "08/18/25",
"9F02": "$1.00",
"9F03": "$0.00",
"9F21": "09:33:17",
"9F26": "11 22 33 44 55 66 77 88",
"9F27": "40",
"9F34": "1E 03 00",
"9F36": "00 01",
"9F37": "866B87CC"
},
"tsi": "E800",
"tvr": "4200008000"
},
"host_response_isocode": "00",
"host_response_text": "CAPTURED",
"host_transaction_reference": "000000051346",
"merchant_id": "xxxxxxxxxxxxxxx",
"receipt_information": {
"endorsement": [
"I AGREE TO PAY ABOVE TOTAL AMOUNT",
"IN ACCORDANCE WITH CARD ISSUER'S",
"AGREEMENT",
"(MERCHANT AGREEMENT IF CREDIT VOUCHER)",
"RETAIN THIS COPY FOR STATEMENT",
"VERIFICATION"
],
"footer": [
"Thank You",
"Please Come Again"
],
"header": [
"ASU Student Accounts 202",
"287 RIVERS ST",
"sdfasdfasdfas",
"855-278-5080"
]
},
"reference_no": "3",
"status": "approved",
"terminal_id": "0000",
"total_amount": "100",
"transaction_amount": "100",
"transaction_date": "25/08/18",
"transaction_time": "09:37:35",
"type": "pre_auth_completion"
}
],
"status": "completed"
}
}
}
Void
When a void request is sent to the payment terminal, the terminal will display a prompt to determine if a sale or pre-auth is to be voided. Once the select is made, an menu will appear to select the transaction to void.
Request
{
"request": {
"flow_id": "474643",
"resource": {
"type": "void",
"amount": "100"
}
}
}
Response
{
"event": {
"flow_id": "474643",
"resource": {
"results": [
{
"account_last4": "0045",
"aid_emv_parameters": [
null
],
"authorization_no": "050142",
"batch_no": "4",
"card": {
"entry_mode": {
"code": "1",
"text": "insert"
},
"type": {
"code": "02",
"text": "mastercard"
}
},
"card_expiration": "1225",
"customer_card_description": "MasterCard",
"customer_language": "0",
"emv": {
"aid": "A0000000041010",
"application_label": "MasterCard",
"data": {
"82": "58 00",
"5F34": "03",
"9A": "08/18/25",
"9F02": "$1.00",
"9F03": "$0.00",
"9F21": "09:18:17",
"9F26": "11 22 33 44 55 66 77 88",
"9F27": "40",
"9F34": "1E 03 00",
"9F36": "00 01",
"9F37": "4C7A9A11"
},
"tsi": "E800",
"tvr": "4200008000"
},
"host_response_isocode": "00",
"host_response_text": "APPROVED",
"host_transaction_reference": "000000051266",
"merchant_id": "xxxxxxxx",
"original_transaction_type": "00",
"receipt_information": {
"header": [
"ASU Student Accounts 202",
"287 RIVERS ST",
"sdfasdfasdfas",
"855-278-5080"
]
},
"reference_no": "4",
"status": "decline_by_host_or_card",
"terminal_id": "0000",
"total_amount": "100",
"transaction_amount": "100",
"transaction_date": "25/08/18",
"transaction_time": "09:19:10",
"type": "void"
}
],
"status": "completed"
}
}
}
Force Transaction
When a force request is sent to the payment terminal, the device will prompt for card entry. Once the card has been entered the device will prompt for authcode entry.
Request
{
"request": {
"flow_id": "474643",
"resource": {
"type": "force",
"amount": "100"
}
}
}
Response
Reprint Receipt
Request
{
"request": {
"flow_id": "474643",
"resource": {
"type": "reprint_receipt",
"reprint_type": "merchant_copy"
}
}
}
Response
{
"event": {
"flow_id": "474643",
"resource": {
"results": [
{
"account_last4": "0045",
"aid_emv_parameters": [
null
],
"authorization_no": "050862",
"batch_no": "4",
"card": {
"entry_mode": {
"code": "1",
"text": "insert"
},
"type": {
"code": "02",
"text": "mastercard"
}
},
"card_expiration": "1225",
"customer_card_description": "MasterCard",
"customer_language": "0",
"cvm_result": "0",
"emv": {
"aid": "A0000000041010",
"application_label": "MasterCard",
"data": {
"82": "58 00",
"5F34": "03",
"9A": "08/18/25",
"9F02": "$1.00",
"9F03": "$0.00",
"9F21": "10:38:17",
"9F26": "11 22 33 44 55 66 77 88",
"9F27": "40",
"9F34": "1E 03 00",
"9F36": "00 01",
"9F37": "4E9D0F3E"
},
"tsi": "E800",
"tvr": "4200008000"
},
"host_response_isocode": "00",
"host_response_text": "APPROVED",
"host_transaction_reference": "000000051446",
"merchant_id": "220614986921",
"receipt_information": {
"endorsement": [
"I AGREE TO PAY ABOVE TOTAL AMOUNT",
"IN ACCORDANCE WITH CARD ISSUER'S",
"AGREEMENT",
"(MERCHANT AGREEMENT IF CREDIT VOUCHER)",
"RETAIN THIS COPY FOR STATEMENT",
"VERIFICATION"
],
"footer": [
"Thank You",
"Please Come Again"
],
"header": [
"ASU Student Accounts 202",
"287 RIVERS ST",
"sdfasdfasdfas",
"855-278-5080"
]
},
"reference_no": "4",
"status": "approved",
"terminal_id": "0000",
"total_amount": "100",
"transaction_amount": "100",
"transaction_date": "25/08/18",
"transaction_time": "10:38:29",
"type": "sale"
}
],
"status": "completed"
}
}
}
Reports
URL : ws://{device ip:50000}/tsi/v1/reports
Recent Error
This request will return the status of a recent transaction
Request
{
"request": {
"flow_id": "580061",
"resource": {
"type": "recent_error"
}
}
}
Response
{
"event": {
"flow_id": "580061",
"resource": {
"results": [
{
"status": "receipt_information"
}
],
"status": "completed"
}
}
}
Custom Data
In addition to the standard information sent in requests to the Bluechip application. Bluefin had added additional field can be included as part of the request. The information included will depend on the requirements of the request. Below is a list of all the additional fields that can be include, a description of its use and am example request/response.
| Parameter | Description |
|---|---|
| group | Groups are pre-configured flexible groups that can be used for various reasons, including: a) to direct transactions to separate back-end merchant accounts or depository accounts. Please work with your Bluefin Representative to configure any of these options. b) to assign transactions to a specific grouping that you wish. |
| custom_id | This is a custom identifier that can be used for any purpose you wish. Often times this is a customer number, or some other foreign key used to match up reports and transactions lists with customer information on your database. For some processors, such as Paymentech, this ID is passed through to the processor and available in their reporting. This can ease syncing up reporting. |
| street_address1 | Street address of the cardholder or bank account holder. |
| street_address2 | Street address of the cardholder or bank account holder. |
| city | The city portion of the cardholder or account holder address. This is not sent to the processor. It is only stored for your reporting purposes. |
| state | State of the cardholder or bank account holder. |
| zip | The 5-digit format or 5+4 formatted zip code of the cardholder or accountholder. For example, 12345 or 12345-1234. Only numbers and a hyphen are allowed. INTERNATIONAL: Can contain any combination of letters or numbers, and either a space or a hyphen. |
| country | This is a 2- or 3-character country code value for the card/account holder: Country codes can be obtained at http://www.iso.org/iso/country_codes Note: We do NOT validate the value. |
| phone | The phone number of the cardholder/account holder. It does not expect any specific format, is not sent to the processor, and is stored only for your reporting use. |
| The email address of the cardholder/account holder. It does not expect any specific format, is not sent to the processor, and is stored only for your reporting use or sending email receipts. | |
| transaction_id | The transaction_id of a previously completed transaction. |
| allow_partial | Allows for the support of partial auths. By default QSAPI assumes all trasactions do not supoort partial auths. |
| level2_tax | Used exclusively for level 2 transactions. Required for level 2 transactions. For Visa cards, value must be expressed as greater than 0.00, for MasterCard value may be expressed as 0.00 if desired. |
| level2_zip | Used exclusively for level 2 transactions. REQUIRED for level 2 transactions and it is probably the same value as the "zip" variable value. This value is not validated like the "zip" variable value, so any alphanumeric value up to 10 digits is valid. |
| level2_order_id | Used exclusively for level 2 transactions. Merchant determines any custom alphanumeric value. |
| level2_merchant_reference | Used exclusively for level 2 transactions. Required for level 2 transactions. Merchant determines any custom alphanumeric value. |
| healthcare_total_amount | |
| prescription_amount | |
| dental_amount | |
| vision_amount | |
| clinical_amount | |
| copay_amount | |
| transit_amount | |
| dynamic_descriptor_name | A dynamic descriptor (also known as a soft descriptor) is a customizable set of information that can be included with a credit card transaction. It can consist of a merchant descriptor, as well as city and state information. This is particularly useful in instances where a merchant's descriptor might differ from the merchant's default DBA (doing business as) name, which is configured with the back-end processor. |
Updated about 10 hours ago