Tokenization API
The 360-One JavaScript Tokenization API provides easy way to achieve PCI compliance through client-side tokenization. The API communicates with the 360-One Payment Gateway by using the cardholders web browser, and the CORS method for secure browser based cross-domain communication.
Note: In order to use the Tokenization API, the requesting domain must be registered with 360-One. Please consult your product certification specialist. Contact Us for more info.
Contents
Live Demo
The following demo shows how a card may be tokenized at the browser level, before it comes in contact with a merchant’s server.
This demo simply calls Mes.tokenize, and displays the result in a pop-up box. In a production situation, the token would be forwarded to the merchant’s server where it’s stored for any future transaction processing. The token has no expiration.
Response:
Description
Typical transaction flow
The basic overview of this API as is follows:
- When a payment form on your site is submitted, invoke the API by calling Mes.tokenize
- The API will provide an array of data to your callback function.
- The array key ‘code’ may be tested to ensure the process was successful (0 was a success).
- In your callback function, you may do whatever you wish to the token, it’s entirely PCI compliant:
- Populate a hidden form element with the token, and continue with the form submission to your server (typical).
- Run another AJAX call to your server to store the token, or have your server perform any gateway transactions using the token.
Supported browsers
The JavaScript tokenization API utilizes XmlHttpRequest in browsers which support it, falling back to XDomainRequest for certain versions of Internet Explorer. Browsers which do not support any form of CORS are not compatible.
| Browser | Supported Version | Supported Version Release |
|---|---|---|
| Firefox | 3.5+ | June 30, 2009 |
| Internet Explorer | 8.0+ | June 3, 2009 |
| Google Chrome | 3.0+ | September 25, 2009 |
| Opera | Opera 12+, Opera Mobile 12+ | June 14, 2012 |
| Android Mobile Browser | All | |
| Chrome for Android | All | |
| Firefox for Android | All | |
| iOS Safari | All |
Implementation
Full example
- <html>
<head>
<title>JS API Test</title>
<script src=“mes-1.0-min.js” type=“text/javascript”></script>
<script src=“http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js” type=“text/javascript”></script><script type=“text/javascript”>
$(document).ready(function() {
$(‘#payment’).submit(function() {
document.getElementById(‘submitButton’).disabled = true;
Mes.tokenize($(‘#card_number’).val(), $(‘#card_exp_date’).val(), responseHandler);
return false; // Our responseHandler will submit the form for us.
});
});function responseHandler(result) {
document.getElementById(‘submitButton’).disabled = false;// Display full result for debugging.
$(‘#result’).html(“Result:<br />”);
for(var i in result) {
$(‘#result’).append(i+“: “+result[i]+“<br />”);
}if(result[‘code’] == 0) {
// Request was successful. Insert hidden field into the form before submitting.
$(‘#payment’).append(‘<input type=”hidden” name=”mesToken” value=”‘+result[‘token’]+‘” />’);
$(‘#payment’).append(‘<input type=”hidden” name=”mesCardNum” value=”‘+result[‘card_number’]+‘” />’);
$(‘#payment’).append(‘<input type=”hidden” name=”mesHash” value=”‘+result[‘hash’]+‘” />’);
// Continue to submit the form to the action, where we will read the mesToken POST data.
document.forms[‘payment’].submit();
}
else {
// Request failed. Check result[‘code’], or use result[‘text’] as a reference, and inform the user.
}
}
</script>
</head><body>
<div id=“container”><!– tokenlistener is any page that can extract mesToken from the post (PHP example: $_POST[‘mesToken’]) –>
<form action=“tokenlistener.php” method=“POST” id=“payment”>
<div class=“formRow”>
<label>Card Number</label>
<input type=“text” size=“20” autocomplete=“off” id=“card_number”/>
</div>
<div class=“formRow”>
<label>Expiration (MMYY)</label>
<input type=“text” size=“4” id=“card_exp_date”/>
</div>
<button type=“submit” id=“submitButton”>Submit</button>
</form><div id=“result”></div>
</div>
</body>
</html>
Once the token has been posted to our form action, any server-side language can be used to extract the token from the POST data. It can then be substituted for a card number for use with the MeS Payment Gateway.
API Result Codes
| Code | Description | Note |
|---|---|---|
| 0 | Request OK | |
| 1 | Browser is incompatible with CORS, tokenization cannot proceed | |
| 2 | Invalid Card Number | |
| 3 | Invalid Expiry Date | |
| 4 | Gateway Error | Additional fields, gateway_text and gateway_error are the exact Payment Gateway text and error which occurred. |
| 5 | HTTP Error | Error 5 will never occur in Internet Explorer 8 and 9. Invalid HTTP codes using these browsers (such as 404, 500, etc) will be reported as error 6; Transmission Error. |
| 6 | Transmission error | |
| 7 | Cross Scheme Error | When using Internet Explorer 8/9, while submitting across schemes (From non-SSL to SSL, or vice versa). This can be avoided by always hosting the page as SSL. |
