Client side Tokenization
Our Secure Payment form for the web has a set of pre-built input elements, which enables you to collect sensitive card information on your checkout page. Novalnet will tokenize (temporarily) the sensitive information, and your server will get in touch with only our tokenized payment data.
This payment form includes the feature:
- While entering the card data, the card data will automatically be formatted
- Translating placeholders into your shopper's preferred language
- Responsive design
- Customizing the CSS style to match the appearance of your checkout page
- Card brand, card number, expiry & CVC will be updated dynamically based on the input
- Option to make your payment form more compact
Include NovalnetUtility
You need to include the NovalnetUtility script on your checkout page (where you will display your credit/debit cards form). It should directly load from https://cdn.novalnet.de/js/v2/ instead of being hosted by yourself.
It is highly recommended to add the https://cdn.novalnet.de/js/v2/NovalnetUtility-1.1.2.js inside the head tag of your payment/checkout page.
HTML
<html>
<head>
<script src="https://cdn.novalnet.de/js/v2/NovalnetUtility-1.1.2.js" integrity="sha384-wRpaQDgV62dqZ/HthwD84Gs9Mgxg5u5PrND0zS9L5rjOdWE8nTDLq+fdsCxbnj6K" crossorigin="anonymous"></script>
</head>
</html>Add Iframe to your payment form
Place an Iframe HTML tag in your payment/checkout page template file where you want the payment form rendered.
Then, add the following hidden fields to store the needed data received during the tokenization process. So, it gets submitted to the Novalnet.
panHash : To store Novalnet's unique identifier for the given payment data
unique_id : To store the random id which belongs to a particular pan_hash
do_redirect : If the value is 1, then you should handle the payment as a redirection
HTML
<html>
<head>
<script src="https://cdn.novalnet.de/js/v2/NovalnetUtility-1.1.2.js" integrity="sha384-wRpaQDgV62dqZ/HthwD84Gs9Mgxg5u5PrND0zS9L5rjOdWE8nTDLq+fdsCxbnj6K" crossorigin="anonymous"></script>
</head>
<body>
<form id="payment_form" name="payment_form" action="/confirmation" method="POST">
<iframe id="novalnet_iframe" frameborder="0" scrolling="no"></iframe>
<input type="hidden" id="pan_hash" name="pan_hash"/>
<input type="hidden" id="unique_id" name="unique_id"/>
<input type="hidden" id="do_redirect" name="do_redirect"/>
<input type="submit" name="submit" id="submit" value="submit">
</form>
</body>
</html>About Client Key
The client key is a unique public key linked to your account. We will then authenticate your client-based calls based on your client key. Here, we will whitelist your domain only through which you can make your Client-side request(s). Therefore, you need your client key for the following purposes:
- To render the secure payment form
- To tokenize (temporarily) the sensitive information
You don't need to use client_key during your server-side API request(s).
Domain whitelist
We allow client-side request(s) only from the whitelisted domain of your particular project. The whitelisted domain should be a valid secure (https://) domain.
In TEST MODE, the whitelisted domain will work for both non-secure (http://) and secure (https://) protocol(s) environments, and also the port value should be included (if applicable).
Once your project has been created, we will whitelist your Main page URL (which you gave during the project creation) by default.
How to get your Client Key
You can find your client key in your Novalnet admin portal in the following path Projects -> [SELECT YOUR DESIRED PROJECT] -> API credentials -> Client Key
You can also get your client_key through Novalnet's merchant/details API along with your merchant details.
Manage your domains
You can add or remove domains that you want to whitelist for client-side authentication in your Novalnet admin portal in the following path Projects -> [SELECT YOUR DESIRED PROJECT] -> API credentials -> Allowed domains -> Edit without changing your client key.
You can whitelist up to 4 domains on your own via the Novalnet admin portal. Please get in touch with our Our support team if you want to add more than 4 domains.
Set your Client Key
You need to set your client key in the Novalnet javascript Library using the function - NovalnetUtility.setClientkey("###YOUR_CLIENT_KEY###");. Based on this, we will authenticate your domain.
Once you set the Client Key to your Novalnet javascript Library, you can access the supportive functions to proceed further.
JAVASCRIPT
// Set Your Client Key
NovalnetUtility.setClientKey("###YOUR_CLIENT_KEY###");Create Credit/Debit Card Form
Now, you need to create the configuration object and pass it to the NovalnetUtility library function - NovalnetUtility.createCreditCardForm(object). This function will create and display the payment form inside the iFrame.
Parameter List
Each request is separated into so-called objects, which indicate an entity.
Each parameter is marked with attributes Mandatory, Conditional , Optional . Based on your necessity, you can use these parameters accordingly.
on_success
Mandatory function(data){document.getElementById('novalnet_pan_hash').value=data['hash'];document.getElementById('novalnet_force_redirect').value=data['do_redirect'];return true;} |
Called once the pan_hash (temp. token) created successfully |
on_error
Mandatory function(data){if(undefined!==data['error_message']){alert(data['error_message']);return false;}} |
Called in case of an invalid payment data or incomplete input |
on_show_captcha
Conditional function(data){document.getElementById('novalnet_iframe').classList.add('.captcha');} |
Called in case the captcha process is enabled for the payment form |
id
Mandatory novalnet_iframe |
The ID of the Iframe in the payment form. It is mandatory to pass the Iframe ID here. Based on which the entire process will took place | ||||||||||||
inline
Optional 1 |
Set to 1 to make your Iframe input container more compact (default - 0) | ||||||||||||
style
|
|
||||||||||||
|
|||||||||||||
text
|
|
||||||||||||
|
|||||||||||||
card_number
|
|
||||||||||||
|
|||||||||||||
expiry_date
|
|
||||||||||||
|
|||||||||||||
cvc
|
|
||||||||||||
|
|||||||||||||
first_name
Conditional Max |
Firstname of the customer. | ||||||||||||||||
last_name
Conditional Mustermann |
Lastname of the customer. | ||||||||||||||||
email
Conditional test@novalnet.de |
Customer's billing email address | ||||||||||||||||
billing
|
|
||||||||||||||||
|
|||||||||||||||||
shipping
|
|
||||||||||||||||
|
|||||||||||||||||
amount
Mandatory 100 |
The total amount to be charged from the customer includes the line items, tax, shipping and additional costs (in minor units), e.g., Euro in Eurocents (5,22€ = 522). |
currency
Mandatory EUR |
The currency in which the transaction is being processed. The three-character currency code as defined in ISO-4217. |
test_mode
Mandatory 1 |
Denotes the processing mode of the transaction in encrypted format. The following values are permitted:
|
enforce_3d
Optional 1 |
If you wish to process the SCA authentication for the Credit/Debit Cards, use this parameter The following values are permitted:
Note: By default, we will do the SCA authentication for the Credit/Debit Cards(cards within Europe region). |
lang
Optional EN |
Language Code as two characters as per ISO 639-1 standards |
JAVASCRIPT
window.onload = function() {
NovalnetUtility.setClientKey("###YOUR_CLIENT_KEY###");
var configurationObject = {
// You can handle the process here, when specific events occur.
callback: {
// Called once the pan_hash (temp. token) created successfully.
on_success: function (data) {
document.getElementById('pan_hash').value = data ['hash'];
document.getElementById('unique_id').value = data ['unique_id'];
document.getElementById('do_redirect').value = data ['do_redirect'];
return true;
},
// Called in case of an invalid payment data or incomplete input.
on_error: function (data) {
if ( undefined !== data['error_message'] ) {
alert(data['error_message']);
return false;
}
},
// Called in case the Challenge window Overlay (for 3ds2.0) displays
on_show_overlay: function (data) {
document.getElementById('novalnet_iframe').classList.add(".overlay");
},
// Called in case the Challenge window Overlay (for 3ds2.0) hided
on_hide_overlay: function (data) {
document.getElementById('novalnet_iframe').classList.remove(".overlay");
}
},
// You can customize your Iframe container styel, text etc.
iframe: {
// It is mandatory to pass the Iframe ID here. Based on which the entire process will took place.
id: "novalnet_iframe",
// Set to 1 to make you Iframe input container more compact (default - 0)
inline: 1,
// Add the style (css) here for either the whole Iframe contanier or for particular label/input field
style: {
// The css for the Iframe container
container: "",
// The css for the input field of the Iframe container
input: "",
// The css for the label of the Iframe container
label: ""
},
// You can customize the text of the Iframe container here
text: {
// The End-customers selected language. The Iframe container will be rendered in this Language.
lang : "EN",
// Basic Error Message
error: "Your credit card details are invalid",
// You can customize the text for the Card Holder here
card_holder : {
// You have to give the Customized label text for the Card Holder Container here
label: "Card holder name",
// You have to give the Customized placeholder text for the Card Holder Container here
place_holder: "Name on card",
// You have to give the Customized error text for the Card Holder Container here
error: "Please enter the valid card holder name"
},
card_number : {
// You have to give the Customized label text for the Card Number Container here
label: "Card number",
// You have to give the Customized placeholder text for the Card Number Container here
place_holder: "XXXX XXXX XXXX XXXX",
// You have to give the Customized error text for the Card Number Container here
error: "Please enter the valid card number"
},
expiry_date : {
// You have to give the Customized label text for the Expiry Date Container here
label: "Expiry date",
// You have to give the Customized error text for the Expiry Date Container here
error: "Please enter the valid expiry month / year in the given format"
},
cvc : {
// You have to give the Customized label text for the CVC/CVV/CID Container here
label: "CVC/CVV/CID",
// You have to give the Customized placeholder text for the CVC/CVV/CID Container here
place_holder: "XXX",
// You have to give the Customized error text for the CVC/CVV/CID Container here
error: "Please enter the valid CVC/CVV/CID"
}
}
},
// Add Customer data
customer: {
// Your End-customer's First name which will be prefilled in the Card Holder field
first_name: "Max",
// Your End-customer's Last name which will be prefilled in the Card Holder field
last_name: "Mustermann",
// Your End-customer's Email ID.
email: "test@novalnet.de",
// Your End-customer's billing address.
billing: {
// Your End-customer's billing street (incl. House no).
street: "Musterstr, 2",
// Your End-customer's billing city.
city: "Musterhausen",
// Your End-customer's billing zip.
zip: "12345",
// Your End-customer's billing country ISO code.
country_code: "DE"
},
shipping: {
// Set to 1 if the billing and shipping address are same and no need to specify shipping details again here.
"same_as_billing": 1,
// Your End-customer's Shipping first name.
first_name: "Max",
// Your End-customer's Shipping last name.
last_name: "Mustermann",
// Your End-customer's Shipping Email ID.
email: "test@novalnet.de",
// Your End-customer's shipping street (incl. House no).
street: "Hauptstr, 9",
// Your End-customer's shipping city.
city: "Kaiserslautern",
// Your End-customer's shipping zip.
zip: "66862",
// Your End-customer's shipping country ISO code.
country_code: "DE"
},
},
// Add transaction data
transaction: {
// The payable amount that can be charged for the transaction (in minor units), for eg:- Euro in Eurocents (5,22 EUR = 522).
amount: ###TRANSACTION_AMOUNT###,
// The three-character currency code as defined in ISO-4217.
currency: "###TRANSACTION_CURRENCY###",
// Set to 1 for the TEST transaction (default - 0).
test_mode: ###TEST_MODE###
},
custom: {
// Shopper's selected language in shop
lang: "EN"
}
}
// Create the Credit Card form
NovalnetUtility.createCreditCardForm(configurationObject);
};Get payment data
Once the shopper enters the card details, your script should call the function - NovalnetUtility.getPanHash(). Then you can get the pan_hash, unique_id and do_redirect values by initiating the function - NovalnetUtility.getPanHash()
In general you can call NovalnetUtility.getPanHash() function on form submit (or) any click event.
JAVASCRIPT
document.getElementById('payment_form').onsubmit = function(event) {
// It will control the getPanHash call, if the pan_hash value already assigned to pan_hash
if(document.getElementById('pan_hash') != undefined && document.getElementById('pan_hash').value == '')
{
event.preventDefault();
event.stopImmediatePropagation();
NovalnetUtility.getPanHash();
}
};Get Height of the Payment Form
If the height of the Payment Form is not fixed in your container (eg., During toggle on click), then you can set the exact height after a certain scenario/event (after the toggle open) by initiating the function - NovalnetUtility.setCreditCardFormHeight()
JAVASCRIPT
// Set Payment form height to your iframe
NovalnetUtility.setCreditCardFormHeight()Sample Script
Please refer to the Novalnet sample pre-built solution, which does the entire things, including the iframe and payment form creation and setting up the communication to the Novalnet server below:
HTMLMIXED
<html>
<head>
<script src="https://cdn.novalnet.de/js/v2/NovalnetUtility-1.1.2.js" integrity="sha384-wRpaQDgV62dqZ/HthwD84Gs9Mgxg5u5PrND0zS9L5rjOdWE8nTDLq+fdsCxbnj6K" crossorigin="anonymous"></script>
</head>
<body>
<form id="payment_form" name="payment_form" action="#" method="POST">
<iframe id="novalnet_iframe" frameborder="0" scrolling="no"></iframe>
<input type="hidden" id="pan_hash" name="pan_hash"/>
<input type="hidden" id="unique_id" name="unique_id"/>
<input type="hidden" id="do_redirect" name="do_redirect"/>
<input type="submit" name="submit" id="submit" value="submit"/>
</form>
</body>
</html>
<script>
window.onload = function() {
// Set your Client key
NovalnetUtility.setClientKey("###YOUR_CLIENT_KEY###");
var configurationObject = {
// You can handle the process here, when specific events occur.
callback: {
// Called once the pan_hash (temp. token) created successfully.
on_success: function (data) {
document.getElementById('pan_hash').value = data ['hash'];
document.getElementById('unique_id').value = data ['unique_id'];
document.getElementById('do_redirect').value = data ['do_redirect'];
document.getElementById('submit').onclick();
return true;
},
// Called in case of an invalid payment data or incomplete input.
on_error: function (data) {
if ( undefined !== data['error_message'] ) {
alert(data['error_message']);
return false;
}
},
// Called in case the challenge window Overlay (for 3ds2.0) displays
on_show_overlay: function (data) {
document.getElementById('novalnet_iframe').classList.add(".overlay");
},
// Called in case the Challenge window Overlay (for 3ds2.0) hided
on_hide_overlay: function (data) {
document.getElementById('novalnet_iframe').classList.remove(".overlay");
}
},
// You can customize your Iframe container styel, text etc.
iframe: {
// It is mandatory to pass the Iframe ID here. Based on which the entire process will took place.
id: "novalnet_iframe",
// Set to 1 to make you Iframe input container more compact (default - 0)
inline: 1,
// Add the style (css) here for either the whole Iframe contanier or for particular label/input field
style: {
// The css for the Iframe container
container: "",
// The css for the input field of the Iframe container
input: "",
// The css for the label of the Iframe container
label: ""
},
// You can customize the text of the Iframe container here
text: {
// The End-customers selected language. The Iframe container will be rendered in this Language.
lang : "EN",
// Basic Error Message
error: "Your credit card details are invalid",
// You can customize the text for the Card Holder here
card_holder : {
// You have to give the Customized label text for the Card Holder Container here
label: "Card holder name",
// You have to give the Customized placeholder text for the Card Holder Container here
place_holder: "Name on card",
// You have to give the Customized error text for the Card Holder Container here
error: "Please enter the valid card holder name"
},
card_number : {
// You have to give the Customized label text for the Card Number Container here
label: "Card number",
// You have to give the Customized placeholder text for the Card Number Container here
place_holder: "XXXX XXXX XXXX XXXX",
// You have to give the Customized error text for the Card Number Container here
error: "Please enter the valid card number"
},
expiry_date : {
// You have to give the Customized label text for the Expiry Date Container here
label: "Expiry date",
// You have to give the Customized error text for the Expiry Date Container here
error: "Please enter the valid expiry month / year in the given format"
},
cvc : {
// You have to give the Customized label text for the CVC/CVV/CID Container here
label: "CVC/CVV/CID",
// You have to give the Customized placeholder text for the CVC/CVV/CID Container here
place_holder: "XXX",
// You have to give the Customized error text for the CVC/CVV/CID Container here
error: "Please enter the valid CVC/CVV/CID"
}
}
},
// Add Customer data
customer: {
// Your End-customer's First name which will be prefilled in the Card Holder field
first_name: "Max",
// Your End-customer's Last name which will be prefilled in the Card Holder field
last_name: "Mustermann",
// Your End-customer's Email ID.
email: "test@novalnet.de",
// Your End-customer's billing address.
billing: {
// Your End-customer's billing street (incl. House no).
street: "Musterstr, 2",
// Your End-customer's billing city.
city: "Musterhausen",
// Your End-customer's billing zip.
zip: "12345",
// Your End-customer's billing country ISO code.
country_code: "DE"
},
shipping: {
// Set to 1 if the billing and shipping address are same and no need to specify shipping details again here.
"same_as_billing": 1,
},
},
// Add transaction data
transaction: {
// The payable amount that can be charged for the transaction (in minor units), for eg:- Euro in Eurocents (5,22 EUR = 522).
amount: 100,
// The three-character currency code as defined in ISO-4217.
currency: "EUR",
// Set to 1 for the TEST transaction (default - 0).
test_mode: 1
},
custom: {
// Shopper's selected language in shop
lang: "EN"
}
}
// Create the Credit Card form
NovalnetUtility.createCreditCardForm(configurationObject);
};
document.getElementById('submit').onclick = function(event) {
// It will control the getPanHash call, if the pan_hash value already assigned to pan_hash
if(document.getElementById('pan_hash') != undefined && document.getElementById('pan_hash').value == '')
{
event.preventDefault();
event.stopImmediatePropagation();
NovalnetUtility.getPanHash();
}
};
</script>