Knowledge Center

Knowledge Center > Commerce > Hosted Commerce Pages > Payment Pages 2.0 > Integrate Payment Pages 2.0

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.

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: 

  • For the Production environment:
<script type="text/javascript" src="https://static.zuora.com/Resources/libs/hosted/<version>/zuora-min.js"></script>
  • For the API Sandbox environment:
<script type="text/javascript" src="https://apisandboxstatic.zuora.com/Resources/libs/hosted/<version>/zuora-min.js"></script>

For example, to use the 1.3.0 version of the Zuora JavaScript library on the Production environment, add the below code in your client code:

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

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.

Payment Pages 2.0 Library Versions

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

Version Description
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.

 

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

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

Add a 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>

Sample Client JavaScript

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",
   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.render(
      params,
      prepopulateFields,
      callback
   );
}
</script>
</head>

<body onload="loadHostedPage();">
   <div id="zuora_payment" ></div>
</body>

 

Last modified
13:16, 23 Jan 2017

Tags

This page has no custom tags.

Classifications

(not set)