Integrated Multi-Merchant

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 for iClient Health

The application of EFTPOS terminals in the health industry involves a common use-case that entails multiple health service providers (Doctors) sharing a single EFTPOS terminal, with the medical practice requiring that the Practice management software (PMS) be able to process the transactions/claims under any of the health service providers allocated to and present on a given EFTPOS terminal. This will ensure that the processed funds are settled into the respective bank accounts for the health service providers that the transactions/claims are processed under without the practice having to manually transfer funds over, which is a substantial process overhead for the practices.

There are two halves to the process given above, the health service providers being allocated to particular Tyro terminals to allow the terminal to be shared by multiple providers each having their own individual Tyro merchant ID (MID), and the PMS then being able to specify which health service provider (represented by a MID - Tyro Merchant ID) the transaction is to be routed to.

The concept of a merchant group makes the first half of this process possible, a merchant group is a configuration scheme for a merchant’s Tyro account that allows the merchant IDs present under an account (usually service providers in a typical case) to all be allocated to the terminals under that account, instead of the usual scenario, where a single location/store is represented by a MID and the terminals under that location only have that MID allocated to them. This concept can be seen illustrated below:

multi-merchant

It can be seen above that the terminals allocated to the account all have MIDs 1-4 allocated to them and are able to process transactions under all of them.

info

It is a prerequisite for the effective use of the multi-merchant feature that the merchant’s account be setup as a merchant group - if the account is not setup as a merchant group, the use of the multi-merchant feature will not be possible, since the PMS will be able to specify a mid explicitly in the transaction or claim request, but the terminal will not have that MID available on it if it is a MID that is diffferent from the allocated MID for that terminal or location. The setting up of the merchant account is the responsibility of the merchant and Tyro, and no action is required for the POS partner, the above description is given for effective understanding of the multi-merchant feature.

The Integrated multi-merchant feature makes the latter half of this process possible i.e. it allows the PMS to specify the merchant ID and the terminal ID in the transaction or claim request. The functions (listed below) allow the merchant and terminal IDs to be specified in the mid and tid fields respectively.

Implementation

Given below are the parameters, functions, example code, and interactive working demos for the integrated multi-merchant feature.

Specification

Parameters:

mid (Integer) - The Tyro merchant ID.
tid (Integer) - The Tyro terminal ID.

These parameters are present in the requestParams object of the following functions:

initiatePurchase (requestParams , transactionCallbacks)
initiateRefund (requestParams , transactionCallbacks)
initiateHealthpointClaim (requestParams , transactionCallbacks)
reconciliationReport (requestParams, responseReceivedCallback)
initiateHealthPointClaim (requestParams, transactionCallbacks)
cancelHealthPointClaim (requestParams, transactionCallbacks)
initiateHealthPointRebateEstimate (requestParams, transactionCallbacks)
initiateFullyPaidEasyclaim (requestParams, transactionCallbacks)
initiatePartPaidEasyclaim (requestParams, transactionCallbacks)
initiateBulkBillEasyclaim (requestParams, transactionCallbacks)
initiateHealthPointClaim (requestParams, transactionCallbacks)
initiateHealthPointClaim (requestParams, transactionCallbacks)
getConfig (callback )
initiateOpenTab (requestParams, transactionCallbacks)
initiateFullyPaidEasyclaim (requestParams, transactionCallbacks)
initiateOpenPreAuth (requestParams, transactionCallbacks)
initiateIncrementPreAuth (requestParams, responseReceivedCallback)
completePreAuth (requestParams, responseReceivedCallback)
terminalInfo (requestParams, responseReceivedCallback)

These parameters are present in the options object for the manualSettlement (responseReceivedCallback, options) function.

Parameter	Type	Description	Required
mid	Integer	Override the configured mid for multi-merchant terminals or if your browser does not support local storage.	Yes
tid	Integer	Override the configured tid for multi-merchant terminals or if your browser does not support local storage.	Yes

Example

Given below is an example Javascript code where the integrated multi-merchant feature is being used to explicitly specify the merchant ID and the terminal ID in the mid and tid fields in the purchase function.

Copy

Copied

var iclient = new TYRO.IClientWithUI(apiKey, posProductInfo);
var merchantId = undefined;
var terminalId = undefined;
var integrationKey = undefined;
var merchantIdTransact = $("#merchantIdTransaction").val();
var terminalIdTransact = $("#terminalIdTransaction").val();
var integrationKeyTransact = $("#integKeyTransaction").val();

function purchase() {
    reset();
var merchantIdTransact = $("#merchantIdTransaction").val();
var terminalIdTransact = $("#terminalIdTransaction").val();
var integrationKeyTransact = $("#integKeyTransaction").val();
    doPurchase($("#amount").val(),merchantIdTransact,terminalIdTransact,integrationKeyTransact);
}

function doPurchase(amount,merchantIdTransact,terminalIdTransact,integrationKeyTransact) {

    iclient.initiatePurchase({
        amount: amount,
        cashout: "0",
        integratedReceipt: true,
        mid: merchantIdTransact,
        tid: terminalIdTransact,
        integrationKey: integrationKeyTransact
    }, {
        receiptCallback: receiptCallbackImpl,
        transactionCompleteCallback: transactionCompleteCallbackImpl
    });
    
}

Response Handling

Once the transaction or claim request is successfully received and processed by the terminal without any issues, the terminal provides the response using the respective callback function for that particular function. The response can be handled in the manner prescribed under the particular function initiated as per normal process. No additional steps are required when handling the response for functions using multi-merchant.

Please refer to the documentation of that particular function for details on the callbacks and how to handle the responses for the individual functions.

Working example

Given below is a JS fiddle example that demonstrates the integrated multi-merchant feature, please pair your terminals using your merchant ID and Terminal ID details, upon successful pairing, the pairing details will be returned and displayed on the screen, any MID-TID-integration key combination can then be used to initiate a transaction, please enter the MID, TID, and Integration key in the "Transaction Merchant ID“, “Transaction Terminal ID“, and “Transaction Integration Key“ fields to declare the parameters for the functions.

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.