Skip to main content

Integrate Payment Pages 2.0

Zuora

Integrate Payment Pages 2.0

This article describes how to set up the client code to integrate the Payment Pages 2.0 to your commerce web page. Address the following in your client code:

  1. Include the Zuora JavaScript library.
  2. Provide the client parameters for Payment Pages 2.0.
  3. Optionally, pre-populate the Payment Pages 2.0 form fields.
  4. Implement the callback function.
  5. Optionally, integrate Payment Pages 2.0 with advanced options.
  6. Render the Payment Pages 2.0 form.
  7. Add a <div> container for Payment Pages 2.0.

When integrating your Payment Pages 2.0, ensure to use the full Zuora URL https://www.zuora.com in your client code. zuora.com is not allowed.

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.

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.

The version of the Zuora JavaScript library is updated only when major changes are included. Changes that do not result in a version update are backward-compatible. Changes that are not backward-compatible will be released with an updated version. If you previously downloaded the latest version of the library to your local but find that an issue that has already been resolved is still happening or find the JavaScript library cannot support certain new features, download the latest version again. 

Payment Pages 2.0 Library Versions

The following versions of the Payment Pages 2.0 JavaScript library are available.

Version Description
1.3.1 Latest version
1.3.0

Includes the support for:

  • Additional form fields
  • The Agreement Check box for UK Direct Debit payment method
  • Event handler for the Agreement Checkbox in the UK Direct Debit type Payment Pages
1.2.0

Includes the following new features: 

  • New functions for custom error handling
  • Handles PCI fields as pre-populated parameters
1.1.0    

This version was deprecated as of the 191 release (August 2015) of Zuora. Upgrade to the latest version of the library.

When you use this version of the library, the parameter values to Z.render function are automatically encoded in Payment Pages 2.0. You should not URL encode the parameter values when passing them to Z.render.

1.0.0

This version was deprecated as of the 191 release (August 2015) of Zuora. Upgrade to the latest version of the library.

This version of the library requires you to URL encode the parameter values when passing them to Z.render.

Event handler functions

In the 1.3.0 or later version of zuora.js, an event handler functionZ.setEventHandleris 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");
    });
    

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. 

When a payment method is created successfully, the parameters, success and refId, are returned and accessed through the response object. TherefIdparameter 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);
}

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.

Parameter Required? Description
params Required Parameters for customizing this Payment Pages 2.0 form.
prepopulateFields Required

Parameters with field ids and values to be pre-populated on the form.

If you do not want to pre-populate any field, pass in an empty set. For example: 

var prepopulateFields = {}
callback Required The callback function that handles the response returned after the form is submitted.

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.

Before invoking Z.render or Z.renderWithErrorHandler, the callback function must be implemented.

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>

Note: 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.

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>