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.

Function

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


kp_iDynamoCardReader_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_iDynamoCardReader_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_DynamoCardReader_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 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:

kp_iDynamoCardReader_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_iDynamoCardReader_connectionStateDidChange

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.

Format
kp_iDynamoCardReader_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_iDynamoCardReader_swipeDidFinishWithData

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.

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

kp_iDynamoCardReader_swipeDidFinishWithTimeout

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

Format
kp_iDynamoCardReader_swipeDidFinishWithTimeout();
		

kp_iDynamoCardReader_swipeDidFailWithError

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

Format
kp_iDynamoCardReader_swipeDidFailWithError(error);
		
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)".

kp_iDynamoCardReader_swipeDidCancel

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

Format
kp_iDynamoCardReader_swipeDidCancel();
		

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