Swipe API: iMag Pro & iMag Pro II Card Readers

Kiosk Pro Enterprise supports card reading with the iMag Pro magnetic stripe card reader from IDTech, which connects via the 30-pin port used on earlier iOS devices, and the iMag Pro II, which connects via the Lightning connector.

This JavaScript API allows you to request a magnetic stripe card swipe, returning the data encoded on the card and/or results of the current swipe (success, fail, timeout, or cancel) to your JavaScript code. This API also supports checking the current 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 iMag Pro ir iMag Pro II'

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_iMagCardReader_requestStateOfSupporting

This function requests the current connection state of iMag Pro card reader. Please note that the app can only work with the reader if it is successfully connected.

Format
kp_iMagCardReader_requestStateOfSupporting();
		

Status

Kiosk Pro will immediately call kp_iMagCardReader_stateOfSupportingDidChange, passing whether the reader is correctly configured in Kiosk Pro settings as a parameter.


kp_iMagCardReader_requestStateOfConnection

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

Format
kp_iMagCardReader_requestStateOfConnection();
		

Status

Kiosk Pro will immediately call kp_iMagCardReader_connectionStateDidChange, passing the current connection state of the reader as a parameter.


kp_iMagCardReader_requestSwipe

This function requests a card swipe from a kiosk visitor. If the iMag Pro is correctly configured in Kiosk Pro's settings and connected (and another swipe request is not currently running), Kiosk Pro will show a special alert requesting the visitor swipe a card. If no swipe is detected in the specified 'timeout' period, the alert be will closed automatically and the page notified.

Format
kp_iMagCardReader_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_iMagCardReader_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_iMagCardReader_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_iMagCardReader_cancelSwipe

This function cancels a card swipe that is in progress.

Format
kp_iMagCardReader_cancelSwipe;
		

kp_iMagCardReader_connectionStateDidChange

This callback is run each time the iMag Pro card reader changes its connection state and also when there is a change to Kiosk Pro's settings.

Format
kp_iMagCardReader_connectionStateDidChange(state);
		
Return values
  • state = connection state as integer. The following states are possible:
    • 0 = disconnected.
    • 1 = powering & in the process of connecting.
    • 2 = connected.
    • 3 = connection process failed. User should eject the reader, check that headphone volume is set to maximum level, and insert the reader again.

kp_iMagCardReader_swipeDidFinishWithData

This callback is run when card swipe triggered by kp_iMagCardReader_requestSwipe is finished successfully and the card's data is successfully read. If the card has two tracks of data, Kiosk Pro automatically return these tracks as separate strings..

Format
kp_iMagCardReader_swipeDidFinishWithData(track1, track2);
		
Return values
  • track1 = data of track 1 as a string.
  • track2 = data of track 2 as a string. Can be empty if current card is single-track.

kp_iMagCardReader_swipeDidFinishWithTimeout

This callback is run when a card swipe request is triggered by kp_iMagCardReader_requestSwipe, but no swipe is detected in the timeout period.

Format
kp_iMagCardReader_swipeDidFinishWithTimeout();
		

kp_iMagCardReader_swipeDidFailWithError

This callback is run if the requested swipe has failed (for example, a mis-positioned or slow card swipe) and/or the card's data could not be correctly extracted.

Format
kp_iMagCardReader_swipeDidFailWithError(errorCode);
		
Return values
  • errorCode - code of error as integer. There are the following error codes:
    • -1001 = the iMag Pro card reader is not enabled in Kiosk Pro's settings.
    • -1000 = a card swipe has already been requested and is currently pending.
    • 1 = unreadable card swipe.

kp_iMagCardReader_swipeDidCancel

This callback is triggered when the card swipe is cancelled by the visitor tapping the 'cancel' button on the swipe request alert.

Format
kp_iMagCardReader_swipeDidCancel();
		

kp_iMagCardReader_stateOfSupportingDidChange

This callback is triggered when the page calls kp_iMagCardReader_requestStateOfSupporting and each time Kiosk Pro's settings change.

Format
kp_iMagCardReader_stateOfSupportingDidChange(supported);
		
Return values
  • supported = supported state as boolean.
    • 1 = returned if iMag Pro card reader is selected in Kiosk Pro's settings.
    • 0 = returned if the setting is disabled or another type of card reader is selected.

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