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>

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.

Add a Checkbox for Stored Credential Consent

If you want Zuora to create a stored credential profile within the created payment method, add a checkbox for the customer to give consent for their payment credentials to be stored on file. For more information about stored credential profiles, see Stored credential transactions for more information.

To use this feature, you must use version 1.3.1 or later of the Zuora JavaScript library. In addition, you must integrate Payment Pages 2.0 as an inline form.

The Payment Pages form does not contain a checkbox for the customer to give consent. You must implement the checkbox and call the Z.setAgreement function in the Zuora JavaScript library when the customer selects the checkbox. You can also use the event handler function Z.setEventHandler to listen on an event and trigger an appropriate action.

Note: After the consent checkbox is selected, the payment method information is always submitted to the payment gateway for validation, regardless of whether any of the following settings are enabled for the gateway instance.

• Verify new payment method
• Verify updated payment method

Here is an example for implementing a consent checkbox:

<!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.3.1/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:"inline",
        key:
            "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC59DglWlsd82ooSVYyXoniF5rln3edz+5tdPLVBXXPDVXDCI9w7sneaj+XQs5LFaHZby117XzE8CFmoskVd2tsGLvXr83gEQ7eCXUrY0NDBFlAs0t+ChkB18VXG2DBbeUCI2poZJpCbpQm4rSvqUeY+8H/+/Stf4hXFWVPEEWyjwIDQAB",
        submitEnabled:"false",
        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
        );
    }

    function onAgree() {
        if(document.getElementById("agreement").checked) {
            if (!Z.setAgreement("External","Recurring","Visa","Your_Ref"))
                return;
        } else {
            if(!Z.setAgreement("","","",""))
                return;
        }
    }

    </script>
</head>

<body onload="loadHostedPage();">
    <div id="zuora_payment" ></div>
    <div id="checkBoxDiv" class="item">
        <input id="agreement" type="checkbox" onclick="onAgree()"> I agree
    </div>
</body>

The Z.setAgreement function has the following parameters:

setAgreement(
    mitConsentAgreementSrc,
    mitProfileType,
    agreementSupportedBrands,
    mitConsentAgreementRef
) 

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>