Skip to main content

Deprecated: Hosted Payment Pages Settings


Deprecated: Hosted Payment Pages Settings

This article describes how to configure a Zuora Hosted Page to be used with Zuora Quotes.

In Zuora Quotes, you can configure to allow your users to add a payment method, e.g., a credit card, while creating a quote. The new payment method is then synced to Zuora when the user sends the quote to Zuora. Introduced in version 5.100 (July 2013), this feature uses the HostedPage component in the Zuora Quotes Component Library and is based on Zuora's hosted payment pages. The resulting implementation is PCI-compliant.

This setting works in both legacy CPQ and CPQ X.

These instructions are for users of Zuora Quotes version 5.100 or higher (Q2 '13 release). If you have an older version, Zuora Quotes version 5.92 or earlier, you can achieve the same functionality, but it involves a more extensive configuration effort. The instructions are available here

Configure a Hosted Payment Pages 2.0

The high level steps to set up a Zuora Hosted Page is:

  1. Set up a Hosted Page in Zuora.
  2. Configure Hosted Page Settings in Salesforce.
  3. Test the Hosted Page.
  4. Embed the Hosted Page to a Visualforce page.
  5. Create a custom button for Hosted Page using the Visualforce page you created in the Step #4.
  6. Add the custom Hosted Page button to the Quote Detail page.
  7. Select the settings for how Zuora will treat the payment methods created by the Hosted Payment Method page.
  8. Test Payment Method submission.

You can create more than one of each type of Hosted Page, configured as needed for different applications or situations.

Advanced customization options for Hosted Payment Pages are available via Hosted Page Component

Set up a Hosted Page in Zuora

To set up a Hosted Page in Zuora:

  1. Create a new Hosted Page as described in Configure Hosted Payment Method Pages and Implement Checkout Pages.
  2. The following property values are important for the Salesforce integration:
    • Hosted Domain - https://<Name space>.<Salesforce server instance>
      • <Name space> denotes the name space of the Visualforce page this Hosted Page is embedded to, "zqu" if a standard Zuora Quotes page or "c" if it is your custom page. 
      • <Salesforce server instance> is the subdomain of the url, the portion of the URL before "".
      • For example,
      •  Note that Salesforce server URL may be changed by Salesforce. When this happens, you need to update this setting. Otherwise, Zuora may refuse to render this Hosted Page in Salesforce anymore.
    • Callback Path
      • For out-of-the-box Hosted Payment Method page: /apex/HPMCallback 
      • For out-of-the-box Checkout Page: /apex/CheckoutCallback?hostedPageName=Z-Checkout
    • CSS - Optionally you can create custom CSS for your Hosted Page, which will be embedded as an iFrame in the Salesforce Visualforce page.  For your convenience, the package contains a sample CSS that you can copy directly into the CSS field.
      1. In Salesforce, navigate to Setup > Develop > Static Resources.
      2. Click HPMCSS.
      3. Click View file.
      4. Copy the file content and paste it into the CSS input field of the Hosted Payment Page definition.
  3. After you save the Hosted Page in Zuora, navigate back to Hosted Pages List and click get api security key. Save the API Security Key value.
  4. in the HTML code section, the iFrame HTML code is displayed. For example:

<iframe id="z_hppm_iframe" name="z_hppm_iframe" src=""></iframe>

Save the values for the following parameters. You need to enter the values in Salesforce as described in the next section.

Zuora Parameter Zuora CPQ Setting
Id in the iFrame HTML Page ID
Tenant ID Tenant ID
API Security Key API Security Token

Configure Hosted Page Settings in Salesforce

To configure Hosted Payment Settings in Salesforce:

  1. On the Zuora Config tab, click Hosted Payment Pages Settings.
  2. Click New Hosted Page Setting.
  3. On the Hosted Page Setting Edit page, enter the following field values.
    • Name - Enter a name to identify this Hosted Payment Method page setting.
      • Enter "Zuora HPM Setting" for the default Hosted Payment page.
      • Enter "Z-Checkout" for the default Checkout page.
    • Zuora Application URL - The Zuora application URL, e.g.,
    • Page ID - Enter the Hosted Page ID you saved above.
    • API Security Token -  Enter the API Security Key you saved above.
    • Zuora Tenant ID - Enter the Tenant ID you saved above.
    • Width -  Enter the width of the Hosted Page iFrame.
    • Height - Enter the height of the Hosted Page iFrame.
  4. Click Save.

Test the Hosted Page in Salesforce

To test the new hosted Page:

  1. In Salesforce, navigate to:
    • apex/zqu__hpm if you are testing a Hosted Payment Method page in version 6.0 or higher. For example,
    • apex/PaymentMethodCreation or apex/HPMSample if you are testing a Hosted Payment Method page in a version older than 6.0. For example,
    • apex/zqu_checkout if you are testing a Hosted Checkout page.
  2. The hosted page you defined above is embedded on the page.
    If you don't see the hosted page, check if the Zuora Hosted Payment Pages Setting is configured correctly.

Add the New Payment Method Button to the Quote Detail Page

To add the New Payment Method button to the Quote Detail page:

  1. On the Quote Detail page, click Edit Layout.
  2. On the Quote Layout page, click Buttons.
  3. Drag New Payment Method to the Custom Buttons section. 
  4. Click Save.

Select Payment Method Settings Option

When the user clicks Send to Zuora to sync the quote and new payment method, Zuora processes the initial payment on the subscription using the new payment method. At that point, Zuora will treat the new payment method in one of three ways which you (the administrator) can define:

  1. Set it as the default payment method, and enable auto-pay for the account.
  2. Set it as the default payment method, but do not change the account's auto-pay.
  3. Do not set it as the default payment method, and do not change the auto-pay setting. This setting gives you the option of using the new payment method for a single payment only. For existing accounts, future payments revert to the account's existing default payment method. For new accounts, no default payment method is set.
  4. To select a payment method processing option:

  5. On the Zuora Config tab, click Quote Configuration Settings.
  6. Click Edit Settings.
  7. In the Electronic Payment Method Processing Options section, click Electronic Payment Method Setting, select one of the settings from the drop-down list:
    • Set default, auto-pay
    • Set default, no auto-pay
    • Do not set default, no auto-pay, process payment only
  8. Click Save.
  9. Be sure to advise your users of the settings you have selected so that they can correctly predict and explain the billing and payment behavior for their customers.

Test Hosted Payment Page Submission

To test submitting the new Hosted Payment Method page to Z-Billing:

  1. On the Quote Detail page, click New Payment Method. If this button does not appear on the Quote Detail page, add the button as described in Add the New Payment Method Button.
  2. The Hosted Payment Method page you defined above appears on the page.
  3. Click Save without entering any values. 
  4. A list of validation error messages returns.
  5. Enter valid payment values and click Save.   
  6. A confirmation message for a successful processing appears.
  7. Log in to the Zuora application.
  8. Navigate to Payments > Payments.
  9. Verify that a new CreditCard payment method has been created.