JavaScript sockets

Callback methods

The following functions need to be implemented by consuming Developers.

  1. CIP.OnResultFunction(result) – Function to be called when transaction results are returned from remote hardware
  2. CIP.OnConfigurationDownloadedFunction()- Function to be called when the configuration has been downloaded
CIP.OnResultFunction =
  function (result) {
    if (result.ResultFields.ResultStatus == true) {
      // Transaction was successful
    } else {
      // Transaction was not successful
    }
  };

The result variable is a JSON object with the following shape:

{
  Action : string,
  ErrorMessage : string,
  ResultFields :  ResultFields
}
CIP.OnConfigurationDownloadedFunction() {

    //When this function is called, the properties ControllerName and Devices 
    //  have been populated with values according to the configuration.
    var deviceSelect = $("#devices");
    $.each(Devices, function (index, device) { 
      //populate the device     select control with device names
        deviceSelect
            .append($("</option")
            .attr('value', device.DeviceName)
            .text(device.DeviceName)
            .prop('selected', device.IsDefault));
    });
}

Public variables

The following variables can be used by consuming Developers.

  • CIP.isTestMode – This property must be set by consuming developers. Bool value indicating whether test mode is on or off.
  • CIP.userName – Unique name for this connection.
  • CIP.ControllerName – Name of the remote hardware controller to send transactions.
  • Devices – Array of remote hardware devices that transactions can be processed on.

Public functions

The following function can be consumed by Developers and should not be assigned to or overwritten.

  • CIP.downloadConfiguration(string)– Call this function to download the configuration settings for your location.
$("#getConfig").on('click', function () {
    var locationId = $("#locationId").val();
    if (locationId) {
        CIP.downloadConfiguration($("#locationId").val());
        $("#locationId").css('border-color', 'Green');
    } else {
        $("#locationId").css('border-color', 'Red');
    }
});

Test account

Please contact our dedicated Integration Specialists group to create test accounts for a specific developer.

Sample transactions

Please note

  • The button that initiates a transaction should be deactivated and/or removed as soon as the command is issued
  • Allowing users to double-click could result in cards being charged multiple times
  • Allowing users to click back during transaction processing may result in a potential for duplicates within the same transaction.

Supporting duplicate detection

The transRef is used to detect duplicate transactions. The credit card terminal will check the previous transaction to see if the transRef, amount and credit card are the same. If they are, then instead of charging the card again, it will simply return the previous approval number.

If your software allows split payments on the same invoice, please append a Payment Id to your receipt\invoice number to avoid accidentally triggering the duplicate detection. For example, if your invoice number is 12345 consider using 12345.1 and 12345.2. Only increment the Payment Id when a transaction is approved.

*If this feature isn’t turned on on your test terminal, please contact our Integration Specialists and ask to have “Local Duplicate Checking” turned on.

Debit Sale

CIP.debitSaleFunction (deviceName, amount, cashier, transactionRef, street, zip).

Call this function to process a debit sale.

CIP.debitSaleFunction(
    deviceName, 
    $("#amount").val(), 
    $("#cashier").val(), 
    $("#transRef").val(), 
    $("#street").val(), 
    $("#zip").val()
);

Credit Sale

CIP.creditSaleFunction (deviceName, amount, uniqueTransRef, cashier, transactionRef, street, zip)

Call this function to process a credit sale.

CIP.creditSaleFunction(
    deviceName, 
    $("#amount").val(), 
    $("#uniqueTransRef").val(), 
    $("#cashier").val(), 
    $("#transRef").val(), 
    $("#street").val(), 
    $("#zip").val()
);

Credit Return

CIP.creditReturnFunction(deviceName, amount, uniqueTransRef, cashier, transactionRef)

Call this function to process a credit return.

CIP.creditReturnFunction(
    deviceName, 
    $("#amount").val(), 
    $("#uniqueTransRef").val(), 
    $("#cashier").val(), 
    $("#transRef").val()
);

Credit Auth

CIP.creditAuthFunction(deviceName, amount, cashier, transactionRef, street, zip)

Call this function to authorize a transaction.

CIP.creditAuthFunction(
    deviceName, 
    $("#amount").val(), 
    $("#cashier")val(), 
    $("#transRef").val(), 
    $("#street").val(), 
    $("#zip").val()
);

Credit Force

CIP.creditForceFunction(deviceName, amount, authCode, uniqueTransRef, cashier, transRef)

Call this function to force a credit sale.

CIP.creditForceFunction(
    deviceName, 
    $("#amount")val(), 
    $("#authCode").val(), 
    $("#uniqueTransRef").val(), 
    $("#cashier").val(), 
    $("#transRef").val()
);

Credit Add Tip

CIP.creditAddTipFunction(deviceName, amount, uniqueTransRef, cashier, transactionRef)

Call this function to add a tip to a previous transaction.

CIP.creditAddTipFunction(
    deviceName, 
    $("#amount").val(), 
    $("#uniqueTransRef").val(), 
    $("#cashier").val(), 
    $("#transRef").val()
);

Adding tips for multiple devices

Tips need to be applied to the deviceName where the transaction originated. For example if the original CreditSale was done on deviceName ‘Terminal1’ then the CreditAddTip must use deviceName ‘Terminal1’.

Adding tips multiple times

  • Tips should be added to the uniqueTransRef of the original transaction and not the uniqueTransRef of Add Tip transaction.
  • CreditAddTip replaces the original amount. For example if the original sale was $10.00 and you wanted to add a $2.00 tip, the Amount should be set to $12.00. If you run a 2nd CreditAddTip for $12.00 the total charged to the card will remain $12.00.

Void

CIP.voidFunction(deviceName, uniqueTransRef, cashier, transactionRef)

Call this function to void a transaction.

CIP.voidFunction(
    deviceName, 
    $("#uniqueTransRef").val(), 
    $("#cashier").val(), 
    $("#transRef").val()
);

VoIding for multiple devices

Voids need to be applied to the deviceName where the transaction originated. For example if the original CreditSale was done on deviceName ‘Terminal1’ then the Void must use deviceName ‘Terminal1’.

Request Signature

CIP.requestSignatureFunction(deviceName, cashier, transactionRef)

Call this function to request a signature.

CIP.requestSignatureFunction(
    deviceName, 
    $("#cashier").val(), 
    $("#transRef").val()
);

Credit Save Card

CIP.saveCreditCardFunction(deviceName, cashier, transRef, street, zip)

Call this function to tokenize a credit card.

CIP.saveCreditCardFunction(
    deviceName, 
    $("#cashier").val(), 
    $("#transRef").val(), 
    $("#street").val(), 
    $("#zip").val()
);

Display Text

CIP.displayTextFunction(deviceName, displayText, cashier, transactionRef)

Call this function to display a message on the device screen.