This is the suitable solution if you want to be able to host the creditcard data collection form on your own page without having to directly manipulate such information.
The flow is the following:
Note: This token can only be used once and within 5 minutes after it has been submitted by the client. If the payment attempt fails a new token has to be requested.
The tokenizer has no external dependency. It is recommended to hotlink this javascript file rather than hosting it yourself, that way you’re guaranteed to always use the latest available version.
<script type="text/javascript" src="https://cdn.syspay.com/js/syspay.tokenizer-current.js"></script>
This key can be found in the API Configuration area of your backend.
syspay.tokenizer.setPublicKey('Your public key');
By default the tokenizer will connect to the live environment. During the implementation phase you will probably want to switch to the sandbox one. To do so, adapt your public key accordingly and change the base URL used like this:
syspay.tokenizer.setBaseUrl("https://app-sandbox.syspay.com/api/v1/public/");
In order to tokenize the card information, you need to:
syspay.tokenizer.tokenizeCard({
number: $('#number').val(),
cardholder: $('#cardholder').val(),
exp_month: $('#exp-month').val(),
exp_year: $('#exp-year').val(),
cvc: $('#cvc').val()
}, callback);
var callback = function(response) {
if (null === response.error) {
// The actual token will be in response.token. Add it to a hidden field and submit the form.
// /!\ Make sure you don't submit the actual card data if they are part of your form.
$('<input type="hidden" name="syspay-token" />')
.val(response.token)
.appendTo('#my-form');
// Optionally, you can send the card's BIN to your server
$('<input type="hidden" name="card-bin" />')
.val(response.details.bin)
.appendTo('#my-form');
$('#my-form').get(0).submit();
} else {
// There was an error
alert(response.message);
}
}
The callback given to syspay.tokenizer.tokenizeCard() will be passed a single response object. Some basic pre-validation is made (data types and a LUHN test on the card number) so the callback could be triggered before requesting the token creation to our API if any of these fail.
This response object will contain the following properties:
| Property | Type | Description |
|---|---|---|
| error | integer|null | If the token creation went fine, the error property will be null, otherwise an integer will indicate the error encountered. (See the table below) |
| message | string|null | The corresponding error message for the given code. (This message will always be in english) |
| token | string|null | The returned token to be submitted by the form, or null if an error occured |
| api_code | integer | In case of request error, the actual API error code will be given here. |
| api_message | string | The corresponding api_code message |
| details | object | Details about the creditcard. The object will be empty if an error occured |
| details.bin | string | Creditcard’s BIN |
| details.fingerprint | string | Creditcard’s unique identifier |
| Code | Description |
|---|---|
| 4 | Invalid or missing cardholder name |
| 8 | Invalid or missing card number |
| 16 | Invalid or missing expiration month |
| 32 | Invalid or missing expiration year |
| 64 | Invalid or missing cvc |
| 128 | Response error - The Syspay API call failed (server-side or network error) |
| 256 | Request error - The card information couldn’t be tokenized or the public key is not valid. When this error occurs the object given to the callback will contain an api_code and an api_message properties with further information |
The following example uses jQuery to handle the form submission and the retrieval of the card data, but it is not required by our library.
Note that the card data inputs do NOT have a name attribute so they are not submitted with the rest of the form. It is your responsibility to make sure that the card data is not submitted to your server.
<html>
<head>
<!-- Required -->
<script src="//code.jquery.com/jquery-1.11.1.min.js"></script>
<script src="//cdn.syspay.com/js/syspay.tokenizer-current.js"></script>
<script>
// This is not required for production usage
syspay.tokenizer.setBaseUrl("https://app-sandbox.syspay.com/api/v1/public/");
// The public key can be found from your merchant backend
syspay.tokenizer.setPublicKey("your-public-key");
// The following function will be called back once the card data will have been submitted to the SysPay API
var callback = function(response) {
if (null === response.error) {
// The request was successfully processed. Add the returned token to the form before submitting it for real.
$('<input type="hidden" name="syspay-token" />')
.val(response.token)
.appendTo('#my-form');
// Optionally, you can send the card's BIN to your server
$('<input type="hidden" name="card-bin" />')
.val(response.details.bin)
.appendTo('#my-form');
// Submit the form
$('#my-form').get(0).submit();
} else {
alert('An error occured: ' + response.message + '(Code: ' + response.error + ')');
return false;
}
};
$(function() {
// Catch form submissions and send the card data to syspay
$('#my-form').submit(function() {
// Submit the card data to Syspay
syspay.tokenizer.tokenizeCard({
number: $('#number').val(),
cardholder: $('#cardholder').val(),
exp_month: $('#exp-month').val(),
exp_year: $('#exp-year').val(),
cvc: $('#cvc').val()
}, callback);
// Prevent form submission
return false;
});
});
</script>
</head>
<body>
<form id="my-form" method="POST" action="/path/to/checkout">
<!-- This will be submitted -->
<label>Email <input type="text" id="email" name="email" /></label>
<!-- This won't -->
<label>Cardholder <input type="text" id="cardholder" /></label>
<label>Card number <input type="text" id="number" /></label>
<label>Expiration month <input type="text" id="exp-month" /></label>
<label>Expiration year <input type="text" id="exp-year" /></label>
<label>CVC <input type="text" id="cvc" /></label>
<input type="submit" value="Checkout" />
</form>
</body>
</html>
Processing a payment on a card linked to a token is done using our standard server-2-server processing API. The only difference is that you don’t send the full card information anymore, but only the token.