Swipe API: Shuttle & UniMag2 Card Readers

This API is designed to work with audio jack magnetic stripe card readers from IDTech, specifically the UniMag II and the Shuttle.

The JavaScript-based API allows your page to request a swipe of a magnetic stripe card and to return information about the status of the swipe (success, fail, timeout, cancel) and the card's data back to your page through callbacks. The API also allows you to get information about the connection state of the card reader.

Functions

Callbacks

Related Settings

Requirements

  • Access JavaScript API
    • By Import - recommended, works both online & offline, requires inclusion of kiosk_functions.js prior to any of the following calls.
    • By Injection - only works offline, may not be available 'onload'.
  • Magnetic Stripe Card Reader & MercuryPay Settings > Card Reader Type = 'IDTech UniMag II or Shuttle'

Sample Code

This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.  

To run sample code, set the app's homepage to http://www.kioskproapp.com/swipe-idtech

Download Sample Code


kp_UniMag2CardReader_requestStateOfSupporting

This function determines whether UniMag II and Shuttle card readers are enabled in Kiosk Pro's settings.

Format
kp_UniMag2CardReader_requestStateOfSupporting();
		

Status

Kiosk Pro will immediately trigger kp_UniMag2CardReader_stateOfSupportingDidChange with the status of the card reader.


kp_UniMag2CardReader_requestStateOfConnection

This function requests the current connection state of the card reader. Note that the connection state of the card reader can change at any time. Other functions in this API can only ust the card reader if it is currently connected.

Format
kp_UniMag2CardReader_requestStateOfConnection();
		

Status

Kiosk Pro will immediately trigger kp_UniMag2CardReader_connectionStateDidChange and pass the current connection state of the card reader.


kp_UniMag2CardReader_requestSwipe

This function requests a card swipe from the visitor. If this card reader is connected and no other request for swipe is being shown, this will trigger a customizable alert with a cancel button. This alert will be shown for the time period defined in the 'requestSwipe();' call; if no valid swipe occurs during that period, it will close automatically and a callback triggered to notify your page of the timeout.

Format
kp_UniMag2CardReader_requestSwipe(swipeInfo);
		
Parameters
  • swipeInfo = comma separated key-value pairs which define the parameters of the swipe alert, including title, message, title of cancel button and timeout. Default values are shown:
    • title = "Swipe Request"
    • message = "Please swipe card."
    • cancelButtonTitle = "Cancel"
    • timeout = 20 seconds.

Example

kp_UniMag2CardReader_requestSwipe('"title":"titleValue","cancelButtonTitle":"Cancel","timeout":20,"message":"messageValue"');

Kiosk Pro will parse these pairs and use: 'titleValue' for the title, 'messageValue' for the message, 'Cancel' for title of cancel button and a timeout of 20 seconds.

Order of key-value pairs does not matter. Also some or all of the key-value pairs can be absent. If a key-value pair is absent, then Kiosk Pro will use the default value shown above for that pair. If swipe parameters are empty or contain errors (for example, missing the closing quotes), then Kiosk Pro will not use swipe parameters and will use only default values for all keys.

In order to use the Swipe Request Settings defined in Kiosk Pro, you can add '**swipe_params_from_settings**' inside the parenthesis instead of the 'swipeInfo' parameters. For example:

kp_UniMag2CardReader_requestSwipe('**swipe_params_from_settings**');

Status

Kiosk Pro will call one of the following callbacks depending on whether the card reader is enabled in Kiosk Pro settings, the current connection state of the card reader, the visitor's actions, and/or the results of the card swipe:


kp_UniMag2CardReader_cancelSwipe

This function cancels a card swipe that is in progress.

Format
kp_UniMag2CardReader_cancelSwipe;
		

kp_UniMag2CardReader_connectionStateDidChange

This callback is triggered each time the connection state of the card reader changes, when the function kp_UniMag2CardReader_requestStateOfConnection is triggered, and when the user enables the card reader in Kiosk Pro's settings.

Format
kp_UniMag2CardReader_connectionStateDidChange(state);
		
Return Values
  • state = connection state as integer. The following states are possible:
    • 0 = disconnected.
    • 1 = powering - the reader is in the process of connection.
    • 2 = connected.
    • 3 = powering timeout - the connection process failed. The user should remove the card reader, insert the reader again, and check that headphone volume is set to maximum level.

kp_UniMag2CardReader_swipeDidFinishWithTransactionDataEx

This callback is triggered when swiping of a card has finished and card data was read successfully. Kiosk Pro automatically divides and returns the card's data by tracks. This API supports reading cards with up to 3 tracks of data.

Supported as of Kiosk Pro Enterprise, version 6.1. For earlier versions, please see deprecated functions included in sample code.

Format
kp_UniMag2CardReader_swipeDidFinishWithTransactionDataEx(cardData);
		
Return Values
  • cardData = dictionary of key-value pairs describing card data encoded on card.
    • card_type = card type (integer). 128 means ISO/ABA card type, otherwise other card type.
    • t1_mask_data = masked/clear data of track1 (string) [optional]
    • t1_encrypted_data = encrypted data of track1 (string) [optional]
    • t2_mask_data = masked/clear data of track2 (string) [optional]
    • t2_encrypted_data = encrypted data of track2 (string) [optional]
    • t3_mask_data = masked/clear data of track3 (string) [optional]
    • t3_encrypted_data = encrypted data of track3 (string) [optional]
    • ksn = key serial number (string) [optional]
    • dsn = device serial number (string) [optional]
    • account_number = masked/clear account number number (string) [optional]
    • card_holder_name = card holder name (string) [optional]
    • expiration_date = expiration date (string) [optional]

kp_UniMag2CardReader_swipeDidFinishWithTimeout

This callback is triggered if no card swipe is detected during the timeout period set as part of the kp_UniMag2CardReader_requestSwipe function call (which defaults to 20 seconds if not otherwise defined).

Format
kp_UniMag2CardReader_swipeDidFinishWithTimeout();
		

kp_UniMag2CardReader_swipeDidFailWithError

This callback is triggered if the requested swipe is not performed successfully or if the card's data cannot be correctly extracted.

Format
kp_UniMag2CardReader_swipeDidFailWithError(errorCode);
		
Return Values
  • errorCode = code of error as integer.
    • -1001 = the card reader is not enabled in Kiosk Pro's settings.
    • -1000 = card swipe has already been requested and so the card reader is currently busy.
    • 1 = bad swipe (for example, the magnetic strip on the card reader has been corrupted or poor swiping technique was used).

kp_UniMag2CardReader_swipeDidCancel

This callback is triggered when card swipe request is manually cancelled by the visitor.

Format
kp_UniMag2CardReader_swipeDidCancel();
		

kp_UniMag2CardReader_stateOfSupportingDidChange

This callback is triggered when user calls function kp_UniMag2CardReader_requestStateOfSupporting and each time when user changes Kiosk's settings.

Format
kp_UniMag2CardReader_stateOfSupportingDidChange(supported);
		
Return Values
  • supported = supported state as boolean.
    • 1 = the card reader is enabled in Kiosk Pro's settings.
    • 0 = the card reader is not enabled in Kiosk Pro's settings.

Still stuck? How can we help? How can we help?