Skip to main content

Advanced Integration of Payment Pages 2.0


Advanced Integration of Payment Pages 2.0

If you want to have full control over the submission of payments and interaction with Zuora, you can implement a separate function in your client for Payment Page submission. Then you tie this function to an external submit button to invoke the function when the button is clicked. The response from payment creation is redirected to the configured callback page that you specified during the Payment Pages 2.0 configuration. 

This advanced integration is supported only for the inline style Payment Page forms.

Below is an additional checklist to implement an inline Payment Page form with the external submit button. See Integrate Payment Pages 2.0 for the standard implementation steps.

  • During Payment Pages 2.0 configuration, set the Hosted Domain and Callback Path fields to form the callback URL.
  • Implement the callback page at the callback URL specified in the Callback Path. 
  • Validate the digital signature returned from Zuora.
  • Set the client parameter for Z.render function, style, to "inline".
  • Set the client parameter for Z.render function, submitEnabled, to "false".
  • In your client, implement your Submit button that invokes a call to the Z.submit function to submit the Payment Page form. See Inline_ButtonOut_CITMIT.jsp in the Payment Pages 2.0 sample code suite on Zuora GitHub site for a sample implementation of a Submit button. For the button-outside integration for processing on-session payments, to avoid double charge, it is highly recommended to implement logic in your code to disable the submit button once it is clicked. 

The following is a modified sample code from Integrate Payment Pages 2.0 to Website. The code was updated to render an inline Payment Page form with the external submit button.

<!DOCTYPE html>
<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=""/></script>
<!-- optional params in case prepopulation of certain fields is desired-->
var prepopulateFields = {
   creditCardAddress1:"123 Any Street",
   creditCardAddress2:"Suite #999",
   creditCardHolderName:"John Doe"
// Sample params for rendering iFrame on the client side
var params = {
   id:"ff80808145b3bf9d0145b3c6812b0008", <!-- pageId-->
   paymentGateway: "DefaultGateway" //payment gateway name

function forwardCallbackURL(response) {
   var callbackUrl = "<%=request.getContextPath()%>/callback?";
   for(id in response) {
      callbackUrl = callbackUrl+id+"="+encodeURIComponent(response[id])+"&";

var callback = function (response) {
   if(!response.success) {
      // Requesting Payment Page failed. Error handling code should be added here. Simply forward to the callback url in sample code.

function loadHostedPage() {

//External button: function to submit form
function submitPage() {

<body onload="loadHostedPage();">
   <div id="zuora_payment" ></div>
   <!--Add additional form fields as needed→
   <!--External button: button to submit form→
   <button onclick="submitPage()">Submit</button>

Implement the Callback Page

After the Payment Pages 2.0 form has been submitted, your user is redirected to the callback page. Zuora returns the following results to the callback page by appending them to the callback URL.

  • When a payment method is successfully created, the following are returned:
    • success
    • refId: Represents the newly created payment method ID in Zuora.
    • Any pass-through parameters specified in the client
    • Any form field marked as Returned in Response in the Payment Page configuration. Only the Credit Card type Payment Pages can have fields returned in response.
    • For one-time payment flow, the following additional fields are returned:
      • paymentId  
      • invoiceId (if the invoice ID was passed in through the payment flow)

    Example callback URL:
  • When a Payment Page submission fails, the following are returned:
    • success
    • errorCode
    • errorMessage

    Example callback URL:

You need to code the callback page to process the response back from Zuora and any pass through parameters from Payment Pages 2.0. 

See Configure Payment Pages 2.0 for setting the Callback Path for the Payment Pages. 

Here is a sample code that implements a callback page. This page parses the response information from the callback and composes a message and display it. Then it calls javascript methods, submitSucceed and submitFail, defined in the parent window for further procedure. For example, if the Payment Page submission failed, it calls submitFail that re-renders the Payment Page, using Z.renderWithErrorHandler, and displays customized error message, using Z.runAfterRender

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<%@ page import="com.zuora.hosted.lite.util.HPMHelper" %>
    String message = "";
    if("Response_From_Submit_Page".equals(request.getParameter("responseFrom"))) {
        // Callback for submitting hosted page.
        if("true".equals(request.getParameter("success"))) {
            // Submitting hosted page succeeded.
            try {
                // Validate signature. Signature's expired time is 30 minutes.            
                request.getParameter("signature"), 1000 * 60 * 30);
            } catch(Exception e) {
                // TODO: Error handling code should be added here.            
                throw e;
            message = 
               "Hosted Page submitted successfully. The payment method id is " 
               + request.getParameter("refId") + ".";
        } else {
            // Submitting hosted page failed.
            message = 
               "Hosted Page failed to submit. The reason is: " 
               + request.getParameter("errorMessage");
    } else {
        // Callback for requesting hosted page. And requesting hosted page failed.
        message = "Hosted Page failed to load. The reason is: " 
           + request.getParameter("errorMessage");
<!DOCTYPE html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, 
   initial-scale=1, maximum-scale=1, user-scalable=no">
<link href="css/hpm2samplecode.css" rel="stylesheet" type="text/css" />
    <div class="firstTitle"><font size="4"><%=message%></font></div>
<script type="text/javascript">
if("Response_From_Submit_Page".equals(request.getParameter("responseFrom"))) {
    if("true".equals(request.getParameter("success"))) {
        // Submitting hosted page succeeded.
    } else {
        // Submitting hosted page failed.

See Callback.jsp in the Payment Pages 2.0 sample code suite on Zuora GitHub site for a complete sample implementation designed for all three styles of Payment Pages 2.0, including overlay, inline with button inside, and inline with button outside.

Callback Function vs Callback Page

The Callback URL in the advanced integration is not the same as the callback JavaScript function required for the basic integration. See Callback Function for the cases when you need to implement the JavaScript callback function.

The following table summarizes the Payment Pages 2.0 callback model to help you correctly design a callback function and/or a callback page.

  Form with the Submit Button Inside Form with the Submit Button Outside
Additional fields required when configuring the Payment Page in Zuora application None Callback Path field
When is the JavaScript callback function called?
  • When the Payment Page request fails
  • When the Payment Page submission fails
  • When the payment method is successfully created
  • When the payment method creation fails
  • When a Payment Page request fails
What does the JavaScript callback function handle? Handles all success or error responses from the Z.render function. Handles only the error responses in Payment Page request from the Z.render function.
What happens after the Payment Page is submitted and Payment Method is created?

Your user is redirected to the callback function.

The callback function processes the response back from Zuora and any pass through-parameters from Payment Pages 2.0. 

Your user is redirected to the callback page

The callback page processes the response back from Zuora and any pass-through parameters from Payment Pages 2.0. 


Customize Error Messages in Advanced Integration

If you implement Payment Pages with the Submit button outside, some errors will be generated after the Payment Page is submitted. Zuora will forward these error messages based on your callback URL. 

Use the Z.runAfterRender function to handle the server-side error messages: 


The function takes one input parameter which is the name of your custom function that handles the server-side error messages.

To customize error messages for Payment Pages with an external submit button:

  1. Define the error handling function.
  2. Use Z.renderWithErrorHandler to handle the client-side error messages.
  3. Use Z.runAfterRender to handle the server-side error messages.

Event Handler for UK Direct Debit Payment Method

When you implement a Payment Page with an external Submit button to accept the UK Direct Debit payment method, you can use the event handler function Z.setEventHandler to trigger an event to enable the Submit button only when users select the Agreement checkbox.

The following is a sample code with the event handler:

Z.setEventHandler('agreement_checked', function(response){

Z.setEventHandler('agreement_unchecked', function(response) {

In the version 1.20 of zuora.js, it is not possible to respond to the click event on the Agreement Checkbox for the external Submit button.