Swipe API: iDynamo Card Reader

Kiosk Pro Enterprise supports the following JavaScript API for working with the iDynamo magnetic stripe card reader from MagTek.

This API allows you to initiate a card swipe, returning resulting card data back to your HTML page or if unsuccessful, informing you of failure, timeout, or cancellation. The API also allows you to check 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 = MagTek iDynamo

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

Download Sample Code


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.

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

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.


This callback which 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 2 tracks of data. As MagTek card readers are only available as encrypted devices, plain-text tracks cannot be returned.

kp_iDynamoCardReader_swipeDidFinishWithData(track1Masked, track1Encrypted, track2Masked, track2Encrypted, account_number, card_holder_name, expiration_date);
Return values
  • track1Masked = masked data of track 1 as a string. Can be empty if current card is single-track.
  • track1Encrypted = encrypted data of track 1 as a string. Can be empty if current card is single-track.
  • track2Masked = masked data of track 2 as a string.
  • track2Encrypted = encrypted data of track 2 as a string.
  • account_number = parsed, masked string containing the card account number.
  • card_holder_name = parsed string containing the card holder's name.
  • expiration_date = parsed string containing the card expiration date.


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



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

Return values
  • error = JavaScript object with the following properties: 
    • error.domain = the type of error being returned.  This will always return 'KPIDynamoCardReaderSwipeErrorDomain'.
    • error.code = a numeric code associated with the specific error. For example, '4', which is associated with a bad swipe.
    • error.description = a text string describing the specific error being returned for use in troubleshooting. For example, "IDynamo Card Reader - bad swipe (track error)".


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


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