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.



Related Settings


  • 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


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.



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


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.



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


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.

  • 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.



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:



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:


This function cancels a card swipe that is in progress.



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.

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.


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..

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.


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



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.

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.


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



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

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?