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
- 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 |
|
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 |
|
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 |
|
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 |
|
For ID Tech iMag Pro & iMag Pro II
Format | kp_iMagCardReader_stateOfSupportingDidChange(supported); |
Return values |
|
For MagTek iDynamo
Format | kp_iDynamoCardReader_deviceTypeDidChange(deviceType); |
Return values |
|
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 |
|
For ID Tech iMag Pro & iMag Pro II
Format | kp_iMagCardReader_connectionStateDidChange(state); |
Return values |
|
For MagTek iDynamo
Format | kp_iDynamoCardReader_connectionStateDidChange(state); |
Return values |
|
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 |
|
For ID Tech iMag Pro & iMag Pro II
Format | kp_iMagCardReader_swipeDidFinishWithData(track1Text, track2Text, track3Text); |
Return values |
|
For MagTek iDynamo
Format | kp_iDynamoCardReader_swipeDidFinishWithData(track1Masked, track1Encrypted, track2Masked, track2Encrypted, account_number, card_holder_name, expiration_date); |
Return values |
|
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 |
|
For ID Tech iMag Pro & iMag Pro II
Format | kp_iMagCardReader_swipeDidFailWithError(errorCode); |
Return values |
|
For MagTek iDynamo
Format | kp_iDynamoCardReader_swipeDidFailWithError(error); |
Return values |
|
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
- To run sample code, set the app's homepage to kioskgroup.com/idtech-api
- To download a .zip of sample code, click here.
- For MagTek iDynamo
- To run sample code, set the app's homepage to kioskgroup.com/magtek-api
- To download a .zip of sample code, click here.
Change Log
- Included in initial version of Kiosk Pro Enterprise. Support for MagTek iDynamo card reader added in version 4.2