Integrated Surcharge

You are ready to start developing your integrated surcharge 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 surcharge with Tyro.

Certification Criteria Document

Given below are the function definitions, example code, and interactive working demos for the integrated surcharge feature.

Overview

Tyro terminals can be configured to support surcharging. Surcharging is the feature that allows merchants to reduce the cost of acquiring card payments by passing the cost of acquiring the transaction onto the cardholder by adding the cost on top of the sale price as a surcharge.

Surcharging with Tyro allows the merchants to specify a percentage surcharge for credit cards on their Tyro Merchant Portal, when initiating the transaction, the POS will pass in a JSON object with the various request parameters for the transaction, the enableSurcharge request parameter from the requestParams object of the initiatePurchase() function is used to enable integrated surcharge for the POS.

The terminal will automatically apply the relevant surcharge rate based on the card type and scheme during the transaction, if enableSurcharge is set to ‘true’, iClient will then return the applied surcharge to the POS in the transaction response, the POS can then use the surcharge amount to include it on the POS sales receipt, any reconciliation reports developed, and store it on the sales invoice for automatic addition of the surcharge onto the refund.

warning

Please note that if your POS does not have a surcharge feature of its own, you must not implement a toggle button for the integrated surcharge feature and set the { 'enableSurcharge': true | false} flag to always true. If your POS has a surcharge feature of its own, then there must be a toggle button to set the { 'enableSurcharge': true | false} flag as true or false. When toggle is on (enableSurcharge:true), the Tyro surcharge must be applied, and the POS side surcharge must not be applied. When toggle is off (enableSurcharge:false), POS surcharge must be applied, and Tyro surcharge must not be applied.

Specification

Parameter Definition	Purpose	Functions where parameter is used	Usage Required
enableSurcharge - Boolean (true or false)	A boolean flag specifying whether POS will be receiving and handling the surcharge amount applied by the Tyro terminal.	The parameter is present in the requestParams object in the initiatePurchase function.	Yes

Demo

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.

Making the request

The POS sets the parameters that comprise the requestParams object as per the requirements of the specific transaction request, for use of the integrated surcharge boolean the following must be set:

The enableSurcharge boolean to indicate whether the terminal will apply the surcharge amount to a given purchase transaction.

Example

Copy

Copied

var amount = '1000';

function doPurchase(amount) {
    iclient.initiatePurchase({
        amount: amount,
        cashout: "0",
        integratedReceipt: true,
        enableSurcharge:true
    }, {
        receiptCallback: receiptCallbackImpl,
        transactionCompleteCallback: transactionCompleteCallbackImpl
    });
}

Refer to the Handling the response section to learn more about handling the response.