Implement the Callback Page | Zuora | Developer Documentation

Learn how to implement a callback page to process responses from Zuora’s Payment Pages 2.0, including handling success and error scenarios.

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: Example callback URL: http://s1.hpm.com:8000/thanks?success=true&refId=2c92c0f84979bc700149830f938c7e66&phone=%2B1%28123%29456-7896&email=mickey%40zuora.com&creditCardCountry=NPL&token=L8Zh6xjRyVuXQzg0s29VPSLZHL3nQKkG&refId=2c92c0f84979bc700149830f938c7e66&field\_passthrough1=Residentia
- 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)

When a Payment Page submission fails, the following are returned: Example callback URL:

http://s1.hpm.com:8000/thanks?success=false&errorCode=HostedPageFieldValidationError&errorMessage=creditCardType%3ANullValue%2C%0A&errorField_creditCardType=NullValue

success
errorCode
errorMessage

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 . For more detailed information, see Advanced Integration of Payment Pages 2.0.

<%@ 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.            
                HPMHelper.validSignature(
                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>
<html>
<head>
<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" />
<title>Result</title>
</head>
<body>
    <div class="firstTitle"><font size="4"><%=message%></font></div>
</body>
</html>
<script type="text/javascript">
<%
if("Response_From_Submit_Page".equals(request.getParameter("responseFrom"))) {
    if("true".equals(request.getParameter("success"))) {
        // Submitting hosted page succeeded.
%>
        window.parent.submitSucceed();
<%
    } else {
        // Submitting hosted page failed.
%>
        window.parent.submitFail("<%=request.getQueryString()%>");
<%
    }
}
%>    
}
</script>

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

	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.