Overview
The CardReader Module is used to either navigate to a URL or call a JavaScript function when an attached card reader decodes data.**
Syntax
| cardReader (Module) <META> Syntax |
|---|
<META HTTP-Equiv="cardreader" content="parameter:value"> |
| CardReader JavaScript Object Syntax: |
|---|
| By default the JavaScript Object 'cardReader' will exist on the current page and can be used to interact directly with the cardReader. |
| To Invoke cardReader methods via JavaScript use the following syntax: cardreader.method();
e.g. cardReader.open(); |
|
To Set cardReader parameters via JavaScript use the following syntax: cardreader.parameter = 'value'; remembering to enclose your value in quotes where appropriate.
e.g. cardReader.pinTimeout = 'value'; |
|
To Set cardReader return events via JavaScript use the following syntax: cardreader.event = JavaScript Function;
e.g. cardReader.readEvent = 'doFunction(%json)'; |
|
To set multiple EMML parameters / events on a single line use the following syntax: cardreader.setEMML("[Your EMML Tags]");
e.g. cardReader.setEMML("pinTimeout:value;readEvent:url('JavaScript:doFunction(%json)');open"); |
Methods
Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.
| Name | Description | Default Value |
|---|---|---|
| open | Opens the card reader. Resets the ReadEvent to "". | Closed |
| close | Closes the card reader | Closed |
Parameters
Items listed in this section indicate parameters, or attributes which can be set.
| Name | Possible Values | Description | Default Value |
|---|---|---|---|
| pinTimeout:[Value] | 0 - 65535 | PIN entry timeout in milliseconds. A value of 65535 sets the timeout to infinite. | 30000->30s timeout |
| pinEntry:[Value] | On, Off | Turns the PIN entry on or off. | OFF |
| panData:[Value] | Any 16 digit number | Sets the card data without the need of a swipe. This parameter should not be called via a Meta tag as doing so simulates a card read. | N/A |
| autoTab:[Value] | Enabled, Disabled | When enabled, appends a tab to any data returned as keystrokes by the cardreader. | "disabled" |
| autoEnter:[Value] | Enabled, Disabled | When enabled, appends a carriage return to any data returned as keystrokes by the cardreader. | "disabled" |
| moduleName:[Value] | MSR9000, MSR9001, MSR9500, MSRCAMEO, MSR7000, DCR7000, MSR55, MSR3000 | This method is present to provide backwards compatibility with PocketBrowser code, devices supported by RhoElements will have a single card reader driver installed as part of the platform. If the device has multiple card reader drivers installed this parameter is used to select which driver to use. The drivers present are output in the log file when the card reader is initialised. This parameter is also used to distinguish between an MSR and a DCR, e.g. if you attach a DCR7000 to your device you can specify that only the MSR functionality is used by specifying this parameter as 'MSR7000' | None |
Events
Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a JavaScript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or JavaScript arrays. Event parameters can be accessed either directly or via JSON objects.
readEvent
readEvent:URL('URI') URI is either a URL or a JavaScript function. If a URL, the browser navigates to the URL when the attached card reader decodes some data. If a JavaScript function, the function is treated as a callback which is invoked when the card reader decodes data. Issuing this tag, automatically opens the card reader, if it has not been opened already.
| ID | Name | Description |
|---|---|---|
| 1 | data | Data read by the card reader. This may be card data, the PAN data extracted from the card data, encrypted PIN block data, or a message. In case of an ISO/ABA card [eg: a financial card], data is encrypted. For other cards, data is in the clear. |
| 2 | mode | Describes the data. This will be either: 'CR','ENCDATA','PAN', or 'MESSAGE'. This equates to card data, encrypted PIN block data, PAN data, or a message, respectively. |
| 3 | encryption | This provides the information regarding the card reader head configuration. Available only on Android and the value can be "encrypted" or "unencrypted". |
| 4 | rawData | This is the raw data read by the card reader from all the tracks. Available only on Android and the value is in HEX format. |
| 5 | track1 | The track1 clear/masked data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track1Status value returned is "true". |
| 6 | track2 | The track2 clear/masked data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track2Status value returned is "true". |
| 7 | track3 | The track3 clear/masked data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track3Status value returned is "true". |
| 8 | track1Status | The status of the track1 clear/masked data read by the card reader. Available only on Android and the value can be "true" or "false". |
| 9 | track2Status | The status of the track2 clear/masked data read by the card reader. Available only on Android and the value can be "true" or "false". |
| 10 | track3Status | The status of the track3 clear/masked data read by the card reader. Available only on Android and the value can be "true" or "false". |
| 11 | track1Encrypted | The track1 encrypted data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track1EncryptedStatus value returned is "true". |
| 12 | track2Encrypted | The track2 encrypted data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track2EncryptedStatus value returned is "true". |
| 13 | track3Encrypted | The track3 encrypted data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track3EncryptedStatus value returned is "true". |
| 14 | track1EncryptedStatus | The status of the track1 encrypted data read by the card reader. Available only on Android and the value can be "true" or "false". |
| 15 | track2EncryptedStatus | The status of the track2 encrypted data read by the card reader. Available only on Android and the value can be "true" or "false". |
| 16 | track3EncryptedStatus | The status of the track3 encrypted data read by the card reader. Available only on Android and the value can be "true" or "false". |
| 17 | ksn | The encrypted KSN serial number read by the card reader. Available only on Android and the value is in HEX format. |
Multi Instance
When multiple RhoElememts applications are running the following considerations should be made: Only the foreground RhoElements application is given access to the card reader hardware, when an application is sent to the background its state will be saved and it will automatically relinquish control of the card reader. When brought back to the foreground, an application previously using the card reader will have its previous configuration (eg. pinTimeout) reapplied to the card reader automatically.
Remarks
General
If the CardReader return URI is "", the cardreader data will be returned as keystrokes. The readevent parameter must be set at least once before the pandata parameter is set. If both the autotab and autoenter parameters are set to "enabled", autoenter will take precedence. An opened card reader must be closed before the attached card reader device and associated modulename parameter are changed.
AutoEnter and AccelerateKey
The AccelerateKey Meta tag controls the behaviour of Accelerate keys on Windows CE, if the Enter key is configured to be non functional then AutoEnter will also appear to not function either
Operational Modes (Backwards compatibility with PocketBrowser)
For the DCR7000 the ModuleName parameter must be set at least once before the readevent parameter is set. If the card reader is an MSR, when a card is swiped it returns the data read from the card. Setting ModuleName to a DCR will cause the card data to be returned followed by the PAN Data before waiting for a PIN to be entered on the keypad. Once entered the PIN will be encrypted and returned by a third ReadEvent. The card must be a validly formatted IATA or ABA card.
Event URI and Parameter Persistence
The ReadEvent URI, the PINTimeout, PINEntry, AutoEnter / AutoTab parameters are page-specific values. When RhoElements performs a page navigate (not a JavaScript callback), the URI is invalidated, the parameters set to their default values and the cardreader is closed. While the cardreader is open, the URI value may be changed via passing a new readevent parameter/value pair. In the case that the CardReader is already open, the readevent parameter will simply update the URI and do nothing to the state of the port.
Invalid parameter values
Any attempt to set a parameter to an invalid value, will result in no effect on the parameter's current value.
Closing the reader while PIN entry pending
There is no way to abort a pending PIN entry (other than the customer pressing the Cancel button), for security reasons. Therefore if the reader is closed or RhoElements is quit during that time it will become unresponsive until a PIN is entered or the PIN timeout occurs.
Blank card data
In certain circumstances it is possible that the card reader may return empty card data. The JavaScript event function should be able to handle this correctly.
Detaching / Reattaching the Card Reader
Applications running in RhoElements should be resilient against the card reader being detached and subsequently reattached. Card data parsing code should be robust against unexpected characters in the first read after reattachment.
Encrypted Card data
The encrypted data is supported only on the card readres that are configured for encryption. Since the encrypted data might contain unreadable characters sometimes it is recommended to use only JSON object method rather than JavaScript '%s' notation.
Navigation to URL on ReadEvent
Because encrypted card data can contain characters not accepted in a URL the ReadEvent should be handled entirely in JavaScript.
Requirements
| RhoElements Version | 1.0.0 or above |
|---|---|
| Supported Devices | All supported devices that have a card reader attachment. |
| Minimum Requirements | You must have the appropriate drivers installed on your device to use the CardReader. You will see which drivers are installed in the RhoElements log file after you attempt to use any of the card reader functions in RhoElements. All necessary drivers should be included as part of the platform for supported devices. |
| Persistence | See Comment Above. |
HTML/JavaScript Examples
The following example sets up the card reader to submit the scanned data to an asp page upon successful decoding
<META HTTP-Equiv="cardreader" Content="readevent:url('http://mypage.asp?Data=%s;Mode=%s')">
The following example sets up the card reader to call a JavaScript function upon successful decoding. The JavaScript function will be called 3 times, once with the raw card data, once with just the pan data extracted from the raw card data, and once with the encrypted pan data if the pin has been supplied by the user within 10s.:
<html>
<head>
<title>RhoElements CardReader Test</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta HTTP-Equiv="CardReader" Content="PINEntry:ON">
<meta HTTP-Equiv="CardReader" Content="PINTimeout:0x2710">
<meta HTTP-Equiv="CardReader" Content="ReadEvent:url('javascript:doTransaction('%s', '%s');')">
<script language="javascript" type="text/javascript">
function doTransaction(data, mode){
switch(mode) {
case 'CR':
alert('Card: '+data);
break;
case 'ENCDATA':
alert('Encoded data: '+data);
break;
case 'MESSAGE':
alert('Error: '+data);
break;
case 'PAN':
alert('PAN data: '+data);
alert('Please turn the unit over and enter the PIN');
break;
}
}
</script>
</head>
<body>
</body>
</html>
The following example closes the card reader
<META HTTP-Equiv="CardReader" Content="Close">
The following example reads the encrypted data from the card reader
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>RhoElements CardReader data Test</title>
<META HTTP-Equiv="CardReader" Content="ReadEvent:url('javascript:doTransaction(%json);')">
<script language="javascript" type="text/javascript">
function doTransaction(j){
switch(j.mode) {
case 'CR':
htmlData.innerHTML = "Encryption = " + j.encryption + "<br>"
+ "Total data = " + j.data + "<br>"
+ "Raw data = " + j.rawData + "<br>"
+ "Unencrypted track1 data = " + j.track1 + "<br>"
+ "Unencrypted track2 data = " + j.track2 + "<br>"
+ "Unencrypted track3 data = " + j.track3 + "<br>"
+ "Unencrypted track1 Status = " + j.track1Status + "<br>"
+ "Unencrypted track2 Status = " + j.track2Status + "<br>"
+ "Unencrypted track3 Status = " + j.track3Status + "<br>"
+ "Encrypted track1 data = " + j.track1Encrypted + "<br>"
+ "Encrypted track2 data = " + j.track2Encrypted + "<br>"
+ "Encrypted track3 data = " + j.track3Encrypted + "<br>"
+ "Encrypted track1 Status = " + j.track1EncryptedStatus + "<br>"
+ "Encrypted track2 Status = " + j.track2EncryptedStatus + "<br>"
+ "Encrypted track3 Status = " + j.track3EncryptedStatus + "<br>"
+ "KSN number = " + j.ksn;
break;
}
}
</script>
</head>
<body>
<br><br><br><br><br>
<DIV id="htmlData">The card data will appear here</div>
</body>
</html>