API: Return Magnetic Stripe Card Data from Swipe

Return data from a magnetic stripe card swipe with the following card readers:

  • ID Tech Shuttle
  • ID Tech UniMag II
  • ID Tech iMag Pro
  • ID Tech iMag Pro II
  • MagTek iDynamo

The API also allows you to check the connection state of the reader being used and returns additional detail about failed card swipes.

In this article

Requirements

Kiosk Pro Enterprise

  • Integration of our JavaScript API into your webpage
    • Sample code to run within the app and download for integration into your own project is available here.
    • Best practices for working with the JavaScript API are available here.
  • App Settings
    • Content > JavaScript API > Access JavaScript API = By Import
    • Card Readers & Payments > Card Reader Type = configured for the reader being used
  • iOS/iPadOS Permissions
    • Microphone - required for readers that connect through the audio jack. More on enabling specific iOS/iPadOS permissions here
  • Physical Hardware
    • One of the card readers listed above. Card readers designed for use with the audio jack can be used with newer iPads without an audio jack through an adapter or hub which allows you to connect power and an audio source through the USB-C port.

Triggers via API Functions

Check Card Reader Type in App Settings

This set of functions allow you to confirm that the card reader you are working with is correctly configured in Kiosk Pro's settings.

For ID Tech Shuttle & UniMag II

Format 
kp_UniMag2CardReader_requestStateOfSupporting();
Triggers Kiosk Pro will immediately trigger kp_UniMag2CardReader_stateOfSupportingDidChange with the status of the card reader.

For ID Tech iMag Pro & iMag Pro II

Format 
kp_iMagCardReader_requestStateOfSupporting();
Triggers Kiosk Pro will immediately trigger kp_iMagCardReader_stateOfSupportingDidChange with the status of the card reader.

For MagTek iDynamo

Format 
kp_iDynamoCardReader_requestDeviceType();
Triggers Kiosk Pro will immediately trigger kp_iDynamoCardReader_deviceTypeDidChange with the status of the card reader.

Check Connection Status

This set of functions allow you to check the current connection state of the card reader you are working with.

For ID Tech Shuttle & UniMag II

Format 
kp_UniMag2CardReader_requestStateOfConnection();
Triggers Kiosk Pro will immediately trigger kp_UniMag2CardReader_connectionStateDidChange with the status of the card reader.

For ID Tech iMag Pro & iMag Pro II

Format 
kp_iMagCardReader_requestStateOfConnection();
Triggers Kiosk Pro will immediately trigger kp_iMagCardReader_connectionStateDidChange with the status of the card reader.

For MagTek iDynamo

Format 
kp_iDynamoCardReader_requestStateOfConnection();
Triggers Kiosk Pro will immediately trigger kp_iDynamoCardReader_connectionStateDidChange with the status of the card reader.

Request a Card Swipe

This set of functions triggers Kiosk Pro to listen for and return the results of a card swipe from the card reader you are working with.

By default, Kiosk Pro shows a native iOS alert requesting the visitor swipe their card with a title of 'Swipe Request', a message 'Please swipe your card.', a button to 'Cancel' the request, and a timeout of 20 seconds. This interface can be customized in a number of ways:

  • through parameters on the call to request a swipe, allowing you to customize the text and duration of the native iOS alert shown.
  • through app settings, allowing you to customize the text and duration of the native iOS alert shown. This requires setting the parameter of the swipe request call to '**swipe_params_from_settings**'.
  • defining a custom graphic to be shown during the swipe request. More information on this here.
  • handling the interface directly through your own code. In this scenario, Kiosk Pro handles the swipe request silently in the background, allowing you to fully customize the visitor experience. More information on this here.

For ID Tech Shuttle & UniMag II

Format 
kp_UniMag2CardReader_requestSwipe(swipeInfo);
Parameters
  • swipeInfo - [array] defining how the swipe alert should be shown. If a key-value pair is absent, then Kiosk Pro will use the default value shown 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. Possible keys and default values are:
    • title - [string] the title of the native iOS alert shown during the swipe request. Defaults to "Swipe Request"
    • message - [string] the message of the native iOS alert shown during the swipe request. Defaults to "Please swipe card."
    • cancelButtonTitle - [string] the cancel button text of the native iOS alert shown during the swipe request. Defaults to "Cancel"
    • timeout - [integer] the timeout duration of the swipe request in seconds. Defaults to 20
  • OR '**swipe_params_from_settings**', which triggers the app to use the Swipe Timeout and Swipe Request Text defined in the app's settings
Examples 
kp_UniMag2CardReader_requestSwipe('"title":"titleValue","timeout":20');
		
kp_UniMag2CardReader_requestSwipe('**swipe_params_from_settings**');
Triggers

Kiosk Pro will trigger one of the following depending on the result of the card swipe request:

For ID Tech iMag Pro & iMag Pro II

Format 
kp_iMagCardReader_requestSwipe(swipeInfo);
Parameters
  • swipeInfo - [array] defining how the swipe alert should be shown. If a key-value pair is absent, then Kiosk Pro will use the default value shown 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. Possible keys and default values are:
    • title - [string] the title of the native iOS alert shown during the swipe request. Defaults to "Swipe Request"
    • message - [string] the message of the native iOS alert shown during the swipe request. Defaults to "Please swipe card."
    • cancelButtonTitle - [string] the cancel button text of the native iOS alert shown during the swipe request. Defaults to "Cancel"
    • timeout - [integer] the timeout duration of the swipe request in seconds. Defaults to 20
  • OR '**swipe_params_from_settings**', which triggers the app to use the Swipe Timeout and Swipe Request Text defined in the app's settings
Examples 
kp_iMagCardReader_requestSwipe('"title":"titleValue","timeout":20');
		
kp_iMagCardReader_requestSwipe('**swipe_params_from_settings**');
Triggers

Kiosk Pro will trigger one of the following depending on the result of the card swipe request:

For MagTek iDynamo

Format 
kp_iDynamoCardReader_requestSwipe(swipeInfo);
Parameters
  • swipeInfo - [array] defining how the swipe alert should be shown. If a key-value pair is absent, then Kiosk Pro will use the default value shown 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. Possible keys and default values are:
    • title - [string] the title of the native iOS alert shown during the swipe request. Defaults to "Swipe Request"
    • message - [string] the message of the native iOS alert shown during the swipe request. Defaults to "Please swipe card."
    • cancelButtonTitle - [string] the cancel button text of the native iOS alert shown during the swipe request. Defaults to "Cancel"
    • timeout - [integer] the timeout duration of the swipe request in seconds. Defaults to 20
  • OR '**swipe_params_from_settings**', which triggers the app to use the Swipe Timeout and Swipe Request Text defined in the app's settings
Examples 
kp_iDynamoCardReader_requestSwipe('"title":"titleValue","timeout":20');
		
kp_iDynamoCardReader_requestSwipe('**swipe_params_from_settings**');
Triggers

Kiosk Pro will trigger one of the following depending on the result of the card swipe request:

Cancel a Card Swipe Request

This set of functions cancels a card swipe that is currently in progress from the card reader you are working with.

For ID Tech Shuttle & UniMag II

Format 
kp_UniMag2CardReader_cancelSwipe();
Triggers

Kiosk Pro will immediately trigger kp_UniMag2CardReader_swipeDidCancel

For ID Tech iMag Pro & iMag Pro II

Format 
kp_iMagCardReader_cancelSwipe();
Triggers

Kiosk Pro will immediately trigger kp_iMagCardReader_swipeDidCancel

For MagTek iDynamo

Format 
kp_iDynamoCardReader_cancelSwipe();
Triggers

Kiosk Pro will immediately trigger kp_iDynamoCardReader_swipeDidCancel

Notifications via API Callbacks

When Card Reader Type Changes in App Settings

This set of callbacks are returned when the Card Reader Type is changed in Kiosk Pro settings or when an API call is made to Check Card Reader Type.

For ID Tech Shuttle & UniMag II

Format 
kp_UniMag2CardReader_stateOfSupportingDidChange(supported);
Return values
  • supported - [integer] representing whether the Card Reader Type is set to 'ID Tech Shuttle or UniMag II' in Kiosk Pro's settings. Possible values are:
    • 1 - Card Reader Type is set to 'ID Tech Shuttle or UniMag II' in Kiosk Pro's settings
    • 0 - Card Reader Type is not set to 'ID Tech Shuttle or UniMag II' in Kiosk Pro's settings

For ID Tech iMag Pro & iMag Pro II

Format 
kp_iMagCardReader_stateOfSupportingDidChange(supported);
Return values
  • supported - [integer] representing whether the Card Reader Type is set to 'ID Tech iMag Pro or iMag Pro II' in Kiosk Pro's settings. Possible values are:
    • 1 - Card Reader Type is set to 'ID Tech iMag Pro or iMag Pro II' in Kiosk Pro's settings
    • 0 - Card Reader Type is not set to 'ID Tech iMag Pro or iMag Pro II' in Kiosk Pro's settings

For MagTek iDynamo

Format 
kp_iDynamoCardReader_deviceTypeDidChange(deviceType);
Return values
  • deviceType - [integer] representing whether the Card Reader Type is set to 'MagTek iDynamo' in Kiosk Pro's settings. Possible values are:
    • 0 - Card Reader Type is set to 'MagTek iDynamo' in Kiosk Pro's settings
    • 2 - Card Reader Type is not set to 'MagTek iDynamo' in Kiosk Pro's settings

When Connection Status Changes

This set of callbacks are returned when the connection state of a card reader changes or when an API call is made to Check Connection Status for a specific card reader.

For ID Tech Shuttle & UniMag II

Format 
kp_UniMag2CardReader_connectionStateDidChange(state);
Return values
  • state - [integer] representing the current connection state of the card reader. Possible values include:
    • 0 - disconnected
    • 1 - connecting and attempting to power card reader
    • 2 - connected
    • 3 - timeout while attempting to connect, meaning that the reader was unable to meet its power requirements and/or 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

For ID Tech iMag Pro & iMag Pro II

Format 
kp_iMagCardReader_connectionStateDidChange(state);
Return values
  • state - [integer] representing the current connection state of the card reader. Possible values include:
    • 0 - disconnected
    • 1 - connecting and attempting to power card reader
    • 2 - connected
    • 3 - timeout while attempting to connect, meaning that the reader was unable to meet its power requirements and/or the connection process failed. The user should remove the card reader and insert the reader again

For MagTek iDynamo

Format 
kp_iDynamoCardReader_connectionStateDidChange(state);
Return values
  • state - [integer] representing the current connection state of the card reader. Possible values include:
    • 0 - disconnected
    • 1 - connecting and attempting to power card reader
    • 2 - connected
    • 3 - timeout while attempting to connect, meaning that the reader was unable to meet its power requirements and/or the connection process failed. The user should remove the card reader and insert the reader again

When a Card Swipe Returns Data

This set of callbacks are returned when a card swipe has been successfully executed through one of the card readers supported.

For ID Tech Shuttle & UniMag II

Format 
kp_UniMag2CardReader_swipeDidFinishWithTransactionDataEx(cardData);
Return values
  • cardData - [array] representing data encoded on the card that has been swiped. Formatted as an associative array of key-value pairs with the following keys:
    • card_type - [integer] representing the card type. Possible values are: 128 means type, otherwise other card type.
      • 128 - ISO/ABA card (standard credit/debit card)
      • 131 - other card type
    • t1_mask_data - [string, can be empty] the unencrypted data on track 1, which may contain masked * characters if the reader is configured for encryption
    • t1_encrypted_data - [string, can be empty] the encrypted data on track 1
    • t2_mask_data - [string, can be empty] the unencrypted data on track 2, which may contain masked * characters if the reader is configured for encryption
    • t2_encrypted_data - [string, can be empty] the encrypted data on track 2
    • t3_mask_data - [string, can be empty] the unencrypted data on track 3, which may contain masked * characters if the reader is configured for encryption
    • t3_encrypted_data - [string, can be empty] the encrypted data on track 3
    • ksn - [string, can be empty] the key serial number
    • dsn - [string, can be empty] the device serial number
    • account_number - [string, can be empty] the credit/debit card number, which may contain masked * characters if the reader is configured for encryption
    • card_holder_name - [string, can be empty] the card holder's name
    • expiration_date - [string, can be empty] the expiration date associated with the credit/debit card

For ID Tech iMag Pro & iMag Pro II

Format 
kp_iMagCardReader_swipeDidFinishWithData(track1Text, track2Text, track3Text);
Return values
  • track1Text - [string, can be empty] the unencrypted data on track 1, which may contain masked * characters if the reader is configured for encryption
  • track2Text - [string, can be empty] the unencrypted data on track 2, which may contain masked * characters if the reader is configured for encryption
  • track3Text - [string, can be empty] the unencrypted data on track 3, which may contain masked * characters if the reader is configured for encryption

For MagTek iDynamo

Format 
kp_iDynamoCardReader_swipeDidFinishWithData(track1Masked, track1Encrypted, track2Masked, track2Encrypted, account_number, card_holder_name, expiration_date);
Return values
  • track1Masked - [string, can be empty] the unencrypted, masked data on track 1
  • track1Encrypted - [string, can be empty] the encrypted data on track 1
  • track2Masked - [string, can be empty] the unencrypted, masked data on track 2
  • track2Encrypted - [string, can be empty] the encrypted data on track 2
  • account_number - [string, can be empty] the unencrypted, masked card account number
  • card_holder_name - [string, can be empty] the unencrypted card holder's name
  • expiration_date - [string, can be empty] the unencrypted card expiration date

When a Card Swipe Returns an Error

This set of callbacks are returned when a card swipe fails with an error.

For ID Tech Shuttle & UniMag II

Format 
kp_UniMag2CardReader_swipeDidFailWithError(errorCode);
Return values
  • errorCode - [integer] representing the type of error that occurred. Possible values are:
    • -1001 - the card reader is not enabled in Kiosk Pro's settings
    • -1000 - a card swipe has already been requested and is currently pending
    • 1 - unreadable swipe (for example, the magnetic stripe on the card has been corrupted or poor swiping technique was used)

For ID Tech iMag Pro & iMag Pro II

Format 
kp_iMagCardReader_swipeDidFailWithError(errorCode);
Return values
  • errorCode - [integer] representing the type of error that occurred. Possible values are:
    • -1001 - the card reader is not enabled in Kiosk Pro's settings
    • -1000 - a card swipe has already been requested and is currently pending
    • 1 - unreadable swipe (for example, the magnetic stripe on the card has been corrupted or poor swiping technique was used)

For MagTek iDynamo

Format 
kp_iDynamoCardReader_swipeDidFailWithError(error);
Return values
  • error - [array] representing the type of error that occurred. Formatted as an associative array of key-value pairs with the following keys:
    • -1001 - the card reader is not enabled in Kiosk Pro's settings
    • domain - [string] the type of error being returned.  This will always return 'KPIDynamoCardReaderSwipeErrorDomain'
    • code - [integer] the numeric code associated with the specific error. For example, '4', which is associated with a bad swipe
    • description - [string] a text string describing the specific error being returned for use in troubleshooting. For example, "IDynamo Card Reader - bad swipe (track error)"

When a Card Swipe Request Ends by Timeout

This set of callbacks are returned when a card swipe fails by timing out. The timeout is based on the duration for the swipe request, which is configured through the API call to request a swipe or in the app's settings.

For ID Tech Shuttle & UniMag II

Format 
kp_UniMag2CardReader_swipeDidFinishWithTimeout();

For ID Tech iMag Pro & iMag Pro II

Format 
kp_iMagCardReader_swipeDidFinishWithTimeout();

For MagTek iDynamo

Format 
kp_iDynamoCardReader_swipeDidFinishWithTimeout();

When a Card Swipe Request is Cancelled

This set of callbacks are returned when a card swipe request is canceled by a visitor.

For ID Tech Shuttle & UniMag II

Format 
kp_UniMag2CardReader_swipeDidCancel();

For ID Tech iMag Pro & iMag Pro II

Format 
kp_iMagCardReader_swipeDidCancel();

For MagTek iDynamo

Format 
kp_iDynamoCardReader_swipeDidCancel();

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.
  • For ID Tech iMag Pro & iMag Pro II
  • For MagTek iDynamo

Change Log

  • Included in initial version of Kiosk Pro Enterprise. Support for MagTek iDynamo card reader added in version 4.2

Related Articles

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