Integrated Purchase, Cashout and Refund
Certification Criteria Document
Overview
Purchase transactions are initiated using the function as defined in the “Specification-Purchase” section. The request parameters are provided by the POS in a Javascript object before initiating the request, and optionally, a cashout amount can also be specified in the request parameters. The transaction is then completed by the cardholder on the terminal. Any questions or inputs required on the POS must be provided by the POS user. At the completion of the transaction, a callback is returned, providing the transaction result payload.
Similarly, refund transactions are initiated using the function as defined in the “Specification - Refund” section. The request parameters are to be provided by the POS in a Javascript object before initiating the request. The transaction is then completed by the cardholder on the terminal. Any questions or inputs required on the POS must be provided by the POS user. At the completion of the transaction, a callback is returned, providing the transaction result payload.
The POS must also code in suitable functions to handle the response data provided by the terminal. These include receipt data (if integrated receipt printing has been enabled) and the transaction completion response. If the POS is using headless iClient, then the POS must also develop additional functions to handle the status updates provided by the terminal and to handle any questions that are raised by the terminal during the transaction.
Specification - Purchase
Function Definition | Purpose | Parameters |
---|---|---|
Boolean initiatePurchase(requestParams , transactionCallbacks ) | Initiates a purchase transaction on the terminal. | 1. requestParams(Object ) - An object containing the parameters shown in the below table. 2. transactionCallbacks (Object) - The set of callback functions to provide feedback and the transaction result, please refer to the Transaction Callbacks section for more details. |
Parameter | Type | Description | Required |
---|---|---|---|
amount | String | The purchase amount (amount to charge the customer) in cents. | Required |
cashout | String | Cash out amount in cents. | Optional (Required only if Cashout is being developed as a feature.) |
integratedReceipt | Boolean | Indicate whether receipts will be printed on the POS (true) or on the terminal (false). | Required |
mid | Integer | Override the configured mid for multi-merchant terminals, or if your browser does not support local storage, or if you have developed headless pairing as a feature. | Optional - Required for headless pairing, multi-merchant, or if your browser does not support local storage. |
tid | Integer | Override the configured tid for multi-merchant terminals or if your browser does not support local storage or if you have implemented headless pairing as a feature. | Optional - Required for headless pairing, multi-merchant, or if your browser does not support local storage. |
integrationKey | String | Supply the integration key if your browser does not support local storage or if you have developed headless pairing or multi-merchant as a feature. | Optional - Required for headless pairing, multi-merchart, or if your browser does not support local storage. |
transactionId | String | Supply a transaction Id to be used for the transaction. | Optional |
healthpointTransactionId | String | The integrated transaction ID of the original HealthPoint Claim (used for gap payments). | Optional (Required only if Tyro HealthPoint has been developed as a feature.) |
enableSurcharge | Boolean | Apply a surcharge to this transaction (if the card used attracts a surcharge). | Required - Set the "enableSurcharge" flag as always true unless POS has its own surcharge feature. If POS has its own surcharge feature, there must be a toggle button. When toggle is turned on, the Tyro surcharge must be applied (enableSurcharge:true), and the POS surcharge must not be applied. When toggle is turned off, POS surcharge must be applied (enableSurcharge:false) and tyro surcharge must not be applied. |
Making the Request
The steps to be followed to initiate a purchase are given as follows:
-
The POS sets the parameters that comprise the requestParams object as per the requirements of the specific transaction request, these parameters include the following:
- amount - the amount is mandatory and the POS must declare it, please make sure that the amount is in cents and that the data type is String.
- The cashout amount - optionally a cashout amount can also be added, please make sure that the amount is in cents and that the data type is String.
- The integratedReceipt boolean to indicate whether the POS or the Tyro terminal is responsible for printing the receipts returned during the course of the transactions. Please note that the receipt data will not be returned to the POS if this is set to ‘false'.
- The POS is required to use the MID, integrationKey, and TID parameters if multi-merchant or headless pairing is used or if your browser does not support local storage.
- transactionId - the POS can also choose to explicitly define a transaction ID to be used for end-to-end reporting in both systems (POS and Tyro system), this is completely optional, if this field is not set, the terminal chooses a transaction ID and assigns it to the transaction.
- healthpointTransactionId - if the purchase transaction is to pay off the gap amount for a HealthPoint claim then the claim’s transaction ID must be included in this field.
- enableSurcharge - this field is mandatory to receive data pertaining to the surcharge that the Tyro terminal applies to the transactions. The enableSurcharge flag has to be set as always true if POS does not have a surcharging feature of its own. If the POS has its own surcharging feature, there must be a toggle button in the Tyro settings page. If the toggle is turned on (enableSurcharge:true), Tyro surcharging must be applied, and POS surcharging must not be applied. If the toggle is turned off (enableSurcharge:false), POS surcharging must be applied, and Tyro surcharging must not be applied.
- The POS calls the initiatePurchase(requestParams, transactionCallbacks) function with the requestParams included.
- The POS must also reference the callback functions in the function invocation, the callback functions are responsible for handling the response, and are covered in more detail in the Handling the response section.
info
More details on the multi-merchant feature can be found in the relevant section for multi-merchant, this is not a retail or hospitality feature, and is used predominantly in the health industry Practice management software.
Purchase Request Example
Given below is an example request for a $10.0 purchase transaction where there is no cashout amount, the POS is not printing the integrated receipts, i.e., the receipts are being printed through the Tyro terminal, and the POS receives the surcharge-related data.
var amount = '1000';
function doPurchase(amount) {
iclient.initiatePurchase({
amount: amount,
enableSurcharge: true,
integratedReceipt: false
}, {
receiptCallback: receiptCallbackImpl,
transactionCompleteCallback: transactionCompleteCallbackImpl
});
}
Tyro Integrated Surcharge:
Please always send this enableSurcharge flag as true in the purchase request, unless the POS has its own surcharge feature. There has to be a toggle button if POS has its own surcharge feature. When the toggle is on (enableSurcharge:true), only the Tyro surcharge must be applied, and the POS surcharge must not be applied. When toggle is off (enableSurcharge:false), only POS surcharge must be applied, and Tyro surcharge must not be applied.
Specification - Refund
Function Definition | Purpose | Parameters |
---|---|---|
Boolean initiateRefund(requestParams , transactionCallbacks ) | Initiates a refund transaction on the terminal. | 1. requestParams - An object containing the following parameters, as shown in the below table. 2. transactionCallbacks (Object) - The set of callback functions to provide feedback and the transaction result, please refer to the Transaction Callbacks section for more details. |
Parameter | Type | Description | Required |
---|---|---|---|
amount | String | The refund amount in cents. | Required |
integratedReceipt | Boolean | Indicate whether receipts will be printed on the POS (true) or on the terminal (false). | Required |
mid | Integer | Override the configured mid for multi-merchant terminals, or if your browser does not support local storage, or if you have developed headless pairing as a feature. | Optional - Required for headless pairing, multi-merchant, or if your browser does not support local storage. |
tid | Integer | Override the configured tid for multi-merchant terminals or if your browser does not support local storage or if you have implemented headless pairing as a feature. | Optional - Required for headless pairing, multi-merchant, or if your browser does not support local storage. |
integrationKey | String | Supply the integration key if your browser does not support local storage or if you have developed headless pairing or multi-merchant as a feature. | Optional - Required for headless pairing, multi-merchart, or if your browser does not support local storage. |
transactionId | String | Supply a transaction Id to be used for the transaction. | Optional |
Making the Request
For a refund the steps differ slightly:
- There can be no cashout associated with a refund.
- There can be no surcharge associated with a refund, i.e., the "enableSurcharge" flag must not be used in the refund request.
- The refund amount should be inclusive of the surcharge amount applied to the original purchase transaction.
- There can be no HealthPoint transaction ID associated with a refund.
The POS must set the request parameters accordingly, Apart from the above, the process to make a request is exactly the same as purchase.
Refund Request Example
Given below is an example request for a $ 10.0 refund transaction where the POS is not printing the integrated receipts i.e. the receipts are being printed through the Tyro terminal.
var amount = '1000';
function doRefund(amount) {
iclient.initiateRefund({
amount: amount,
integratedReceipt: false
}, {
receiptCallback: receiptCallbackImpl,
transactionCompleteCallback: transactionCompleteCallbackImpl
});
}
Demo
Given below is a JS fiddle demo that demonstrates the integrated purchase and refund features, additionally cashout option and the custom transaction ID option are also available. Please choose a transaction amount, add in any cashout required, specify a custom transaction ID (if required) and press the purchase or refund button to initiate the respective transaction. Additionally, the “Continue last transaction” function is also given.
JS Fiddle
Please don't click on the Save button if you make any changes in the JS Fiddle sample app. Instead, please press run if you have made any changes. If you click on save, it may break the functionality of the JS Fiddle.
For handling the response, please refer to the Transaction Callbacks section.