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

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:

  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.
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.

Copy
Copied
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.

Copy
Copied
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

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.

Copyright © Tyro Payments 2019-2022. All right reserved.