Skip to main content

Provide a Callback Page

Zuora

Provide a Callback Page

  1. Last updated
  2. Save as PDF

This article is for the Hosted Payment Method Pages (HPM) 1.0. Zuora has deprecated HPM1.0. There are no further plans for HPM 1.0 and Zuora will no longer provide support for any issues with HPM 1.0. Payment Pages 2.0 are now generally available, and are a replacement for HPM 1.0. To migrate from HPM 1.0 to Payment Pages 2.0, see this migration guide.

Overview

After the hosted page has been submitted, a callback will be issued to the callback URL as configured. The callback page will receive the result of the call to Zuora to submit the payment and to retrieve the payment page. The callback page is also responsible for processing the resulting parameters of when Zuora tries to create a payment method.

Return URL Parameters

When a payment method is created successfully, the parameters, success and refId, are returned. refId represents the newly created payment method ID in Zuora:

http://yourdomain.com/yourapp/zuora_callback.jsp?success=true&refId=4028e6963554eb60013558e2e68d1fac

When a hosted page submission fails, the parameters, success, errorCode, and errorMessage will be returned:

http://yourdomain.com/yourapp/zuora_callback.jsp?success=false&errorCode=GeneralSystemError&errorMessage=This is some error message

Error Parameters

An additional parameter will be appended for every enabled field that had an error. For example, if the Name on Card field is enabled in configuration but not entered in the iFrame, the following will be appended onto the callback URL in the format errorField_Field-Name.  A full list of error field names and error codes can be found in Error Handling for Hosted Payment Method Page.

errorField_creditCardHolderName=NullValue

Process Return URL Parameters

The following is an example callback page code. 

<script>
function callback() {
        if (param("success") == true) parent.hp_cback_success(param("refId"));
        else parent.hp_cback_fail(param("errorCode"), param("errorField_creditCardType"), ...);
}
</script>
<body onload="callback();"/>

Zuora recommends that you use the callback page as a simple proxy for transmitting the data from Zuora to your subscription form. You should implement two JavaScript methods on the subscription page: One to handle success and one to handle failures. The following is a sample code:

function hp_cback_success(ref_id) {
        document.HostedPaymentMethodPageForm.paymentMethodId.value = ref_id;
        document.HostedPaymentMethodPageForm.submit();
}
function hp_cback_fail(errorCode, errorMessage, ...) {
//display an error message
}

What's Next

Next, verify the callback response.

  1.