Integrate Payment Pages 2.0

Include the Zuora JavaScript Library

Payment Pages 2.0 provides an out-of-box JavaScript library that encapsulates the implementation details with a simple interface. This hosted library manages server and client-side code and makes future upgrades easier - without any client code changes. 

The JavaScript library includes the functions that:

• Requests and renders Payment Pages 2.0 based on your input parameters
• Handles the submission of Payment Pages 2.0
• Calls the custom callback function that handles the response from Zuora
• Customizes error messages

In your client code, include the latest version of the Zuora JavaScript library as follows: 

<script type="text/javascript" src="https://static.zuora.com/Resources/libs/hosted/<version>/zuora-min.js"></script>

For example, to use the 1.3.1 version of the Zuora JavaScript library, add the following code in your client code:

<script type="text/javascript" src="https://static.zuora.com/Resources/libs/hosted/1.3.1/zuora-min.js"></script>

Zuora recommends that you use the latest version of JavaScript library.

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

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:

  • 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. 

  See "Implement the Callback Function" below for more information.

• 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. 

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);
}

Render the Payment Pages 2.0 Form

The Z.render function takes the client parameters, pre-populated fields, and the callback function and loads the Payment Pages 2.0 form on your client web page. 

The following table lists the input parameters to the Z.render function.

var prepopulateFields = {}

The following is a sample call to the Z.render function: 

Z.render(
   params,
   prepopulateFields,
   callback
);

If you are implementing custom error handling for Payment Pages 2.0, use the Z.renderWithErrorHandler function instead of Z.render. See Customize Error Handling for Payment Pages 2.0 for information about Z.renderWithErrorHandler. 

The size of Zuora’s iFrame will be automatically adjusted based on the elements and content within iFrame. For example, Zuora will resize iFrame to properly handle the CAPTCHA challenges or the 3DS2 challenges. If you want to customize iFrame resizing, it is recommended to use the Z.renderWithErrorHandler function to implement your resizing logic.

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

<!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>