Integrated Purchase, Cashout and Refund

You are ready to start developing your integrated multi-merchant feature now that you have successfully setup your POS to initiate and process requests through iClient in the test environment. Before you begin, please have a look at the certification criteria, which provide a checklist of the minimum requirements for the certification of integrated multi-merchant with Tyro.

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

Making the Request

The steps to be followed to initiate a purchase are given as follows:

1. 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.
2. The POS calls the initiatePurchase(requestParams, transactionCallbacks) function with the requestParams included.
3. 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.

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
    });
}

Specification - Refund

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.

Demo - JS Fiddle

For handling the response, please refer to the Transaction Callbacks section.