Downloading the Zuora JavaScript Library for Customizations

Zuora does not recommend downloading a version of the JavaScript library and maintaining a customized version in the code.

You may choose to download the library if you require customizations that are not yet supported by the latest version of Zuora JavaScript library. Zuora cannot guarantee that your customized version will remain compatible with new releases of Payment Pages 2.0.

The name of the formatted library to download is zuora.js . It is located at the same location as referenced above.

Event handler functions

In the 1.3.0 or later version of zuora.js , an event handler function Z.setEventHandler is available for you to listen on an event and trigger an appropriate action.

Z.setEventHandler("EVENT_NAME", function() {
// trigger an action when the event (EVENT_NAME) is captured.
}

The following events are supported in the event handler function.

• onloadCallback The callback function is invoked when the HPM iframe is loaded. No callback parameters will be passed back to this function. See Integrate Payment Pages 2.0 as an overlay form for examples.

• agreement_checked and agreement_unchecked When you implement a Payment Page with an external Submit button to accept the UK Direct Debit payment method, you can use these event handler functions to enable the Submit button only when users select the Agreement checkbox. See the example about implementing a Payment Page with an external Submit button to accept the payment method .

• onCaptchaStateChange You can use this event handler function to implement the end-user interaction with the CAPTCHA challenge.

• onSubmit Use this event handler to listen to the Payment Page submission event and trigger actions when the event is captured. Here is an example where an alert is shown and the payment page is scrolled to the specified position when the event is captured. Z.setEventHandler('onSubmit', function(response){ alert("Test event handler for onSubmit"); Z.scroll(100, 200); });

• onCancelMandatePage Use this event handler to listen to the event that the confirmation dialog of a Bank Transfer Payment Page is canceled and trigger actions when the event is captured. Here is an example. Z.setEventHandler('onCancelMandatePage', function(response){ alert("Test event handler for onCancelMandatePage"); });

• cardBinInfo Use this event handler to listen to the event that a card number is entered and trigger actions to capture the following BIN information: Here is an example where alerts are shown when the event is captured: Z.setEventHandler('cardBinInfo', function(response) { alert(response.code); alert(response.cardClass); alert(response.cardProductType); });

  Note: To enable and use the cardBinInfo event handler, submit a request at Zuora Global Support .

  • Card brand

  • Card class

  • Card product type

  • Issuer

  • Issuing country code

The Z.setEventHandler function described in this section and other functions, including Callback , Z.render , and Z.renderWithErrorHandler , described in later sections, are designed to support synchronous calls.

Provide Parameter Values for Payment Pages 2.0

The Z.render function that loads the Payment Pages 2.0 form to your webpage requires a set of parameters. See Client Parameters for Payment Pages 2.0 for the required and optional parameters for Payment Pages 2.0.

Provide the parameters in a JavaScript object as key-value pairs as shown in the following sample parameter declaration:

var params = {
    tenantId:"123",
    id:"ff80808145b3bf9d0145b3c6812b0008", 
    token:"qJ52b1iCyPXyZTcuQbfZa2qmKhD4qBGz",
    signature:"MjJmYjBmNTY3ZWI3ZjcyZTRmMjZlZWVhMTJhZDhiYWI1ZjUyMGRkNQ==",
    style:"overlay",
    key:"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC59DglWlsd82ooSVYyXoniF5rln3edz+5tdPLVBXXPDVXDCI9w7sneaj+XQs5LFaHZby117XzE8CFmoskVd2tsGLvXr83gEQ7eCXUrY0NDBFlAs0t+ChkB18VXG2DBbeUCI2poZJpCbpQm4rSvqUeY+8H/+/Stf4hXFWVPEEWyjwIDQAB",
    submitEnabled:"true",
    locale:"fr_FR", 
    url:"https://www.zuora.com/apps/PublicHostedPageLite.do",
    paymentGateway:"DefaultGateway" 
};

The style parameter controls how the Payment Pages 2.0 form is rendered:

• inline - The Payment Pages 2.0 form is embedded within your commerce page. If you specify this style of form, use the submitEnabled parameter to choose whether the page submission is handled by Zuora or by your commerce page: See "Implement the Callback Function" below for more information.

  • true - The Payment Pages 2.0 form contains an internal submit button and the page submission is handled by Zuora.

  • false - The Payment Pages 2.0 form requires an external submit button to handle the page submission.

• overlay - The Payment Pages 2.0 form appears as an overlay when the form is loaded. In this case, the submitEnabled parameter has no effect.

Implement the Callback Function

After your Payment Pages 2.0 form has been rendered and submitted, a callback will be issued to the JavaScript callback function.

When a payment method is created successfully, the parameters, success and refId , are returned and accessed through the response object. The refId parameter represents the newly created payment method ID in Zuora.

• If you specified any pass-through parameters, those parameters and their values are returned. You access these parameter values through the response object and the pass through field names, e.g., response.field_passthrough1 .

• If you selected any form field to be Returned in Response during page configuration, the form field name and its value are returned. You access these form values through the response object and the form field name, e.g., response.creditCardCountry . See Payment Pages 2.0 Form Fields for the list of form fields.

A callback function is required for the following types of implementation:

• For the Overlay forms and Inline forms with the internal submit button, the JavaScript function "callback" is required to handle the response from the Payment Pages.

var function callback(response) { if(response.success) { // Handle the response after the Payment Page is

// successfully submitted. } else { if(response.responseFrom == "Response_From_Submit_Page") { // Handle the error response when the Payment Page

// submission failed. } else{ // Handle the error response when the Payment Page

// request failed. } } }

• For the Inline forms with the external submit button, the JavaScript function "callback" is required to handle error responses from Payment Page request, e.g. incorrectly configured hosted domain. Success responses and error responses from Payment Page submission are handled at the callback URL. See Advanced Integration of Payment Pages 2.0 for information about the callback URL in this implementation option.

var function callback(response) { if(!response.success) { // Handle the error response when the Payment Page request failed. } }

Here is a sample implementation of a simple callback function.

function callback(response) {
   var redirectUrl = "";
   if(response.success) {
      redirectUrl = 
         "https://yourdomain.com/yourapp/callback.jsp?refid="
         + response.refId + "&field_passthrough1="
         + response.field_passthrough1;
      window.location.replace(redirectUrl);
   } 
   else {
      if(response.responseFrom == "Response_From_Submit_Page") {
         // Handle the error response when the Payment Page submission failed.
         redirectUrl = 
            "https://yourdomain.com/yourapp/callback.jsp?success=false&errorcode="
            + response.errorCode 
            + "&errorMessage=" + response.errorMessage;
      }
      else{
         // Handle the error response when the Payment Page request failed.
      }
   }
   window.location.replace(redirectUrl);
}

Add an HTML Container for Payment Pages 2.0

In your client HTML code, add a container to house the Payment Pages form. The container must have the id, zuora_payment , as shown below:

<div id="zuora_payment" ></div>

When specifying the style attribute of the container, consider the following best practices:

• Ensure that the display style attribute of the container is not set to none . If you implement logic to hide the container for the Payment Pages form for a certain reason, ensure to include the logic of displaying the container again.

• If a scrollbar is added to the container and a height is set, such as <div id="zuora_payment" style="height: 300px; overflow:auto"> , the popup window, such as the 3DS2 challenge window, might not appear in the expected location if the container height is smaller than the iFrame form height. To address this, customize the CSS of the iFrame form in Zuora UI. Add a new CSS element to configure the iFrame form height and support the scrollbar based on the container size. Here is an example: #HostedPageForm { height:300px; overflow: auto; } This configuration ensures the iFrame form has a fixed height, so the popup windows always appear in the center of the fixed-height form, regardless of the end user's scrolling.

Scroll the page to a specified position

In your client code, you can use the Z.scroll function to scroll the page to a specified position.

Z.scroll(x, y);

In the following example, the Z.scroll function is used in the onSubmit event handler and scrolls the payment page to the specified position when the event is captured.

Z.setEventHandler('onSubmit', function(response){
   Z.scroll(100, 200);
});

Sample Client JavaScript

Overlay Form

The following is a sample client JavaScript for integrating Payment Pages 2.0 as an overlay form:

<!DOCTYPE html>
<html>
<head>
<meta name="viewport" 
   content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
<!-- Zuora Public javascript library -->
<script type="text/javascript" 
   src="https://static.zuora.com/Resources/libs/hosted/1.1.0/zuora-min.js"/></script>
<script>
<!-- optional params in case prepopulation of certain fields is desired-->
var prepopulateFields = {
   creditCardAddress1:"123 Any Street",
   creditCardAddress2:"Suite #999",
   creditCardCountry:"USA",
   creditCardHolderName:"John Doe"
};
// Sample params for rendering iframe on the client side
var params = {
   tenantId:123,
   id:"ff80808145b3bf9d0145b3c6812b0008", <!-- pageId-->
   token:"qJ52b1iCyPXyZTcuQbfZa2qmKhD4qBGz",
   signature:"MjJmYjBmNTY3ZWI3ZjcyZTRmMjZlZWVhMTJhZDhiYWI1ZjUyMGRkNQ==",
   style:"overlay",
   key:
    "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC59DglWlsd82ooSVYyXoniF5rln3edz+5tdPLVBXXPDVXDCI9w7sneaj+XQs5LFaHZby117XzE8CFmoskVd2tsGLvXr83gEQ7eCXUrY0NDBFlAs0t+ChkB18VXG2DBbeUCI2poZJpCbpQm4rSvqUeY+8H/+/Stf4hXFWVPEEWyjwIDQAB",
   submitEnabled:"true", 
   locale:"fr_FR", 
   param_supportedTypes:"AmericanExpress,JCB,Visa,MasterCard,Discover,Dankort",
   url:"https://www.zuora.com/apps/PublicHostedPageLite.do",
   paymentGateway:"DefaultGateway" //payment gateway name
};
function callback(response) {
   if(response.success) {
      var redirectUrl = 
         "../thanks?refid="+response.refId+"&field_passthrough1="
         +response.field_passthrough1;
      window.location.replace(redirectUrl);
   } else {
      alert("errorcode="+response.errorCode + ", errorMessage="+response.errorMessage);
   }
}
function loadHostedPage() {
   Z.setEventHandler("onloadCallback", function() {
      // do something when HPM iframe is loaded.
      console.warn("HPM page is loaded.");
   });
   Z.render(
      params,
      prepopulateFields,
      callback
   );
}
</script>
</head>
<body onload="loadHostedPage();">
   <div id="zuora_payment" ></div>
</body>