Build Your Integration

Include the Hosted Payment Session JavaScript library (hpf.js) in the payment page and set the merchant ID:

<script id="hpfScript" src="https://paymentgateway.commbank.com.au/form/v3/hpf.js"></script>

<script>HostedForm.setMerchant(<my merchantId>);</script>

You must collect the card details (card number, security code, expiry month and expiry year) from the payer and pass them in the HostedForm.createSession( )/HostedForm.updateSession( ) method. Below is a sample HTML form that collects all the card details.

 <!-- REPLACE THE action URL with the payment URL on your webserver -->
 <form name="myform" method="POST" action="https://my.company.com/pay">

 <!-- Name attributes are not provided for the card details to stop them from being submitted to your web server as part of the form submission -->
 Card: <input type="text" id="cardNumber"> 
 CSC: <input type="text" id="cardSecurityCode"> 
 Month: <input type="text" id="expiryMonth">
 Year: <input type="text" id="expiryYear">

 <!-- Other fields can be added to enable you to collect additional data on the payment page -->
 Email: <input type="text" name="email">

 <!-- The hidden values below can be set in the updateSessionCallback function as they are returned when creating the session -->
 <input type="hidden" name="sessionId" id="sessionId">
 <input type="hidden" name="cardBrand" id="cardBrand">
 <input type="button" value="Pay" onclick="doCheckout()">
 </form>

The HPF.js library provides the following methods to create and/or update a session, which are called when the card details are submitted.

Create a Session

You can create a session using the HostedForm.createSession( ) method, which takes the card details collected from the payer and a callback function as parameters.

 HostedForm.createSession(sessionDetails, createSessionCallback);

Alternatively, you can create a new session by calling the HostedForm.updateSession( ) method without passing a session identifier.

HostedForm.updateSession(sessionDetails, updateSessionCallback);

Below is some sample code that shows how to call the HostedForm.createSession() or the HostedForm.updateSession() method to create a new session.

 // Collect the card details based on the 'id' of the form elements
 var getSessionDetailsFromForm = function() {
   return {
        cardNumber: document.getElementById('cardNumber').value,
        cardSecurityCode: document.getElementById('cardSecurityCode').value,
        cardExpiryMonth: document.getElementById('expiryMonth').value,
        cardExpiryYear: document.getElementById('expiryYear').value
    }
 }
 // Call doCheckout() from the form submit onClick() event
 var doCheckout = function() {
 var sessionDetails = getSessionDetailsFromForm();
 HostedForm.createSession(sessionDetails, callback);
 // HostedForm.updateSession(sessionDetails, callback);
 };

Update a Session

If you call HostedForm.updateSession( ) method by passing a session identifier, then the details for the session, if it exists, are updated. This is useful if you already have a session containing details such as billing and shipping address but wish to add the payment details to the session later in the checkout flow. Or, if you wish to collect different card details from the payer because the previously collected card details are not acceptable, for example, card brand not accepted.

HostedForm.updateSession(sessionId, sessionDetails, updateSessionCallback);

Below is some sample code that shows how to call the HostedForm.updateSession() method to update an existing session.

 // Collect the card details based on the 'id' of the form elements
 var getSessionDetailsFromForm = function() {
   return {
        cardNumber: document.getElementById('cardNumber').value,
        cardSecurityCode: document.getElementById('cardSecurityCode').value,
        cardExpiryMonth: document.getElementById('expiryMonth').value,
        cardExpiryYear: document.getElementById('expiryYear').value
    }
 }
 // Call doCheckoutWithExistingSession() from the form submit onClick() event
 var doCheckoutWithExistingSession = function(sessionId) {
 var sessionDetails = getSessionDetailsFromForm();
 HostedForm.updateSession(sessionId, sessionDetails, callback);
 };
 

When CommWeb payment gateway processes your form, the response is handled by a callback function that you must define in your web page. This function receives an object describing the result of the HostedForm.createSession( ) or HostedForm.updateSession( ) call.

If the response.status is 'ok', your web page should pass the returned session identifier to your web server so that it can be used to invoke a transaction. If the response.status is 'fields_in_error', your web page should parse individual fields for errors. For error codes, see Handling Payment Form Errors.

Below is some sample code that includes the session identifier and the card brand element in the payment form which is submitted to your web server.

 var callback = function(response) {
   if (response.status === "ok") {
      // call your server to do the payment with the response.session value  
      // this is where we populate the hidden values in the form
      var sessionIdElement = document.getElementById("sessionId");      
      sessionIdElement.value = response.session;
     
      // card brand is not required to be submitted, but shown here as an optional field
      // the response object contains the full list of fields
      var cardBrandElement = document.getElementById("cardBrand");      
      cardBrandElement.value = response.cardBrand;
     
      document.myform.submit();
   } else if (response.status === "request_timeout") {
     // handle the timeout for example by giving the payer the possibility to retry
   } else if (response.status === "fields_in_error") {
     // check in the response.fieldsInError object to see which field was marked as invalid or missing     
        if (response.fieldsInError.cardNumber === "invalid") {
         document.getElementById('cardNumber').style.color="red";
        } else if (response.fieldsInError.cardExpiryMonth === "invalid") {
         document.getElementById('expiryMonth').style.color="red";
        } else if (response.fieldsInError.cardExpiryYear === "invalid") {
         document.getElementById('expiryYear').style.color="red";
        } else if (response.fieldsInError.cardSecurityCode === "invalid") {
         document.getElementById('cardSecurityCode').style.color="red";
        }  
   } 
   
   } else if (response.status === "invalid_session") {
     // handle invalid session details for example by giving the payer the possibility to retry with different card details. If the new details are correct, you can call the updateSession( ) method
   } else {
     // add system error handling here. Typically this would mean the integration is not working properly because there is no response from the client library. 
     // this could result in displaying a page to the payer to try again later and call support 
   }
  };