Hosted Fields

This guide will walk you through the creation of a credit card payment form using the HiPay Hosted Fields.

You will see how to create your payment form, customize it, interact with it, and securely get a token generated from sensitive card information. This token will enable you to make a transaction using the HiPay Order API.

Please follow these 7 steps to create your payment form with the HiPay Hosted Fields and request a new payment :

      1. Set up the HiPay Enterprise JavaScript SDK
      2. Set up your HTML form
      3. Create the payment product instance
      4. Customize your payment form
      5. Interact with the form
      6. Tokenize card information
      7. API ORDER


To collect sensitive information securely, the HiPay Enterprise JavaScript SDK will generate components hosted by HiPay on your page.  With these components, sensitive information filled in by customers never hits your page or your web server.

There are two ways of integrating the HTML in your page:

Automatic Mode

This mode is the easiest one to integrate and also to keep up to data, as HiPay will be able to update it remotely. You simply have to place a div with a unique id in your page. The form will be injected inside automatically.

<form id="hipay-form">
    /* The whole form will be inserted in this div */
    <div id="hipay-hostedfields-form"></div>

    <div class="multiuse-container">
      <input type="checkbox" id="save-card" name="save-card">
      <label for="save-card">Save card</label>

    <button type="submit" id="hipay-submit-button" disabled="true">

    <div id="hipay-error-message"></div>

Custom Mode

The advantage of this integration is that you can personalize the order in which the fields are going to be displayed, even though it will require more development time from your side to keep it up to date.

You simply have to replace input elements by div elements. These elements need to have a unique id.

<form id="hipay-form">
    /* Cardholder field will be inserted here */
    <div class="hostedfield" id="hipay-card-holder"></div>
    <label>Card number</label>
    /* Card number field will be inserted here */
    <div class="hostedfield" id="hipay-card-number"></div>
    <label>Expiry date</label>
    /* Expiry date field will be inserted here */
    <div class="hostedfield" id="hipay-expiry-date"></div>
    /* CVC field will be inserted here */
    <div class="hostedfield" id="hipay-cvc"></div>
    <button type="submit" id="hipay-submit-button" disabled="true">
    <div id="hipay-error-message"></div>

In this example, the HiPay Enterprise JavaScript SDK will generate a Hosted Field in the hipay-card-holder, hipay-card-number, hipay-expiry-date, hipay-cvc divs.

Payment Product Instance

Automatic Mode

Now that the HTML div is ready, we can generate all the fields with their label inside. Set template to auto to activate automatic mode and set the id in selector.

    var config = {
        template: 'auto',
        selector: 'hipay-hostedfields-form' // form container div id
    var cardInstance = hipay.create('card', config);

Custom Mode

Now that the HTML form is ready, we can generate fields inside. To do so, you need to create an instance of a credit card with the HiPay Enterprise JavaScript SDK instance previously initialized.

    var config = {
        fields: {
            cardHolder: {
                selector: 'hipay-card-holder' // card holder div id
            cardNumber: {
                selector: 'hipay-card-number' // card number div id
            expiryDate: {
                selector: 'hipay-expiry-date' // expiry date div id
            cvc: {
                selector: 'hipay-cvc', // cvc div id
                helpButton: true // activate the help button
    var cardInstance = hipay.create('card', config);

Go to: hipay.create(type, options) to see all supported configurations.


There are two ways to customize the Hosted Fields integration, as we separate internal styling from container styling.

Container styling

To best match your style guides, the external styling (height, border, background, etc.) of the field completely depends on your cascading style sheets.

To help you with this integration, the following classes have been added to the container field:

      • HiPayField–empty
      • HiPayField–focused
      • HiPayField–valid
      • HiPayField–invalid

Go to: Hosted Fields container

Internal styling

Internal styling refers to the properties inside generated fields, like text or icon properties. These CSS properties are set during Step 3. Let’s now add styles to our previous configuration.

    var config = {
        template: 'auto',
        selector: 'hipay-hostedfields-form',
        styles: {
            base: { // default field styling
              color: "#000000",
              fontSize: "15px",
              fontWeight: 400,
              placeholderColor: "#999999",
              iconColor: '#00ADE9',
              caretColor: "#00ADE9"
            invalid: { // invalid field styling
              color: '#D50000',
              caretColor: '#D50000'
    var cardInstance = hipay.create('card', config);


You can interact with the card instance previously initialized by listening to events on it.

Here is how to enable your submit button when your form is valid and show the error(s), if not.

    /* Listen to change event on card instance */
    cardInstance.on('change', function(event){
        /* Display error(s), if any */
        document.getElementById("hipay-error-message").innerHTML = event.error;
        /* Enable / disable submit button */
        document.getElementById("hipay-submit-button").disabled = !event.valid;


To securely transmit sensitive information, the HiPay Hosted Fields convert it into a token to be sent to the HiPay Order API to process your payment. With this token, you will never be able to retrieve the card information.

You can tokenize the information of the card you initialized previously by calling the getPaymentData() function. 

The best way to tokenize is to add an event listener on the submit event of your form.

The card.getPaymentData() function returns a Promise. When successful, it returns an object with the token and all the payment data. When rejected, it returns the list of errors.

    /* Get the form */
    let cardForm = document.getElementById("hipay-form");
    /* Add event listener on the submit button when clicked */
    cardForm.addEventListener("submit", function(event) {
      /* Tokenize your card information when the submit button is clicked */
        function(response) {
          /* Send token to your server to process payment */
        function(errors) {
          /* Display first error */
          document.getElementById("hipay-error-message").innerHTML = errors[0].error;

Here is the response from getPaymentData():

    "payment_product": "visa",
    "token": "f12bfab3b4fs5q6der7895a98ab76",
    "request_id": "0",
    "brand": "VISA",
    "pan": "411111xxxxxx1111",
    "card_holder": "JOHN DOE",
    "card_expiry_month": "12",
    "card_expiry_year": "2031",
    "issuer": "ANY BANK",
    "country": "US",
    "card_type": "CREDIT",
    "device_fingerprint": "..." 


Once you have the response from the getPaymentData(), you should use the following parameters to call the HiPay Entreprise Order API.

getPaymentData()Order API parameterComment

The payment method used for the transaction. Depending on the payment product, parameters specific to the payment method are required.


Specific to credit or debit card payment products. This is the token obtained from the HiPay Enterprise Secure Vault API when tokenizing a credit or debit card.


Specific to the PSD2. Object containing the browser information.The ipaddr and http_accept of the browser_info Order API parameter have to be added by your server.

You must enter the client’s IP and not the IP of your server or any other equipment. (Reverse-proxy)

Most CMS and frameworks have methods to get this IP.


This element should contain the value of the ioBB hidden field.

One click & Recurring

By default, a card that is tokenized with the hosted fields cannot be reused as part of a recurring payment.

If you have an integration that allows one click, you must take into account the choice of the end user and activate or not the option.

To activate the option, this method is available.


Here you have an example:

var saveCardCheckbox = document.getElementById('save-card');

saveCardCheckbox.addEventListener('change', function (event) {

Card Validity Controls

The Hosted Fields have some controls in place to make sure the card information validity. The controls applied at this moment are:

Card Number: Numbers only, and card number existence.

Cardholder Name: Maximum length of 60 characters, no more than 8 numbers and no special characters.

Expiry Date: Valid month (between 1 & 12),  valid year (between current year & current year + 15).

CVC: Three numbers, four numbers for AMEX cards.