Hosted Fields

HiPay 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

HTML Set Up

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 here */
    <div id="hipay-hostedfields-form"></div>
 
    <button type="submit" id="hipay-submit-button" disabled="true">
        PAY
    </button>
 
    <div id="hipay-error-message"></div>
</form>

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">
    <label>Fullname</label>
    /* 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>
 
    <label>CVC</label>
    /* CVC field will be inserted here */
    <div class="hostedfield" id="hipay-cvc"></div>
 
    <button type="submit" id="hipay-submit-button" disabled="true">
        PAY
    </button>
 
    <div id="hipay-error-message"></div>
</form>

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.

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

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.

<script>
    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);
</script>

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

Customize

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.

<script>
    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);
</script>

Interact

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.

<script>
    /* 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;
    });
</script>

Tokenize

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.

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

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": "..." 
}

Payment

Once you have the response from the getPaymentData(), you should use it to make a call to HiPay Entreprise Order API.

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.