Skip to main content

PaymentPage Component


PaymentPage Component

The PaymentPage component embeds a Zuora Payment Page as an iFrame on a Visualforce page. This component enables you to use Payment Pages 2.0 within Zuora Quotes to integrate the Zuora payment processing with quotes. 

You must have installed Zuora Quotes, version 6.30+ to use Payment Pages 2.0.

See  Payment Pages Settings for more information about embedding a Payment Page on a Visualforce page with the PaymentPage component.

See Use Case: Create a Payment Page Button for a use case of the component, including a sample Visualforce page for a custom button and the Quote Wizard.

The PaymentPage component supports the following:

  • Renders Payment Pages in two style options, overlay or inline
  • Renders Payment Pages with the option to put the Submit button in the form or outside the form
  • Provides a callback page that verifies the digital signature sent from the Zuora server and handles the callback processing.
  • Ability to to pass additional parameters to Zuora and payment gateways using the HostedPageLitePlugin

The PaymentPage component consists of:

  • PaymentPage.component: The component to be embedded on Visualforce pages
  • PaymentPageController.class: The Apex class that stores the configuration options for the PaymentPage component

PaymentPage Component Attributes

The PaymentPage component accepts the following attributes.

zuoraPageId String Required

Id of the Payment Page in Zuora.

If a blank or a null value is given, the default Payment Page id will be used.

See Retrieve Payment Page Settings in Zuora Quotes for designating a default Payment Page.

style String Optional

Style of the Payment Page.

The accepted values are:

  • overlay
  • inline

The default value is inline.

submitEnabled Boolean Optional

If set to true, the Submit button is rendered inside the Payment Pages iFrame.

The default value is true.

PaymentPage Component Plugins

The PaymentPage component includes the following plugins that you can use to customize Payment Pages. 

  • zqu.PaymentPageController.IHostedPageLiteDoCancelPlugin
  • zqu.PaymentPageController.IHostedPageLiteGoBackPlugin
  • zqu.PaymentPageController.IHostedPageLiteGoNextPlugin
  • zqu.PaymentPageController.IHostedPageLitePlugin


Implement the HostedPageLiteDoCancelPlugin to add custom logic when user clicks the Cancel button to cancels the Quote Wizard. This plugin can be executed only if the page is used within a valid Quote Wizard context and if the payment page Submit button is outside the Payment Page (submitEnabled = false).

Method Signature: PageReference doCancel(String paymentMethodType)

Default Implementation: zqu.PaymentPageController.DefaultHostedPageLiteDoCancelPlugin

Custom Do Cancel Plugin Example

The following custom Do Cancel Plugin redirects the page to the Opportunity Detail page when user clicks Cancel on the Payment Page. 

global class MyDoCancelPlugin implements zqu.PaymentPageController.IHostedPageLiteDoCancelPlugin {
	global PageReference doCancel(String paymentMethodType) {
		String cancelUrl = '/apex/zqu__QuoteList';

		// If in the quote wizard context, cancel the quote wizard using the opportunity id if it can be determined.
        if(ApexPages.currentPage().getParameters().containsKey('stepNumber') && ApexPages.currentPage().getParameters().containsKey('quoteType')) {
            String oppId = ApexPages.currentPage().getParameters().get('oppId');
            if(String.isBlank(oppId)) {
                Id quoteId = ApexPages.currentPage().getParameters().get('id');
                if(String.isNotBlank(quoteId)) {
                    List < zqu__Quote__c> quoteList = [SELECT Id, zqu__Opportunity__c FROM zqu__Quote__c WHERE Id = :quoteId];
                    if(!quoteList.isEmpty()) {
                        oppId = quoteList[0].zqu__Opportunity__c;
            if(String.isNotBlank(oppId)) cancelUrl = '/' + oppId;
            return zqu.QuoteWizardManager.cancel(cancelUrl);
		return new PageReference(cancelUrl);


​Implement the HostedPageLiteGoBackPlugin to add custom logic when user clicks the Back button. This plugin can be executed only if the Submit button is outside the Payment Page (submitEnabled = false).

Method Signature: PageReference navigateBack(String paymentMethodType)

Default Implementation: zqu.PaymentPageController.DefaultHostedPageLiteGoBackPlugin

Custom Go Back Plugin Example

​The following custom Go Back Plugin appends additional parameters, Billing Account Id and Subscription Id, to the target URL when user clicks Back on the Payment Page.

global class MyGoBackPlugin implements zqu.PaymentPageController.IHostedPageLiteGoBackPlugin{
    global PageReference navigateBack(String paymentMethodType) {
        // If the current page is in the Quote Wizard context, the previous page should be determined by the Quote Wizard.
        if(ApexPages.currentPage().getParameters().containsKey('stepNumber') && ApexPages.currentPage().getParameters().containsKey('quoteType')) {
            Map < String, String > quoteContextParams = new Map < String, String >();
            // Get the quote based on the id in the url
            String quoteId = ApexPages.currentPage().getParameters().get('Id');
            zqu__Quote__c quote = [select id, zqu__ZuoraAccountId__c, zqu__ExistSubscriptionId__c from zqu__Quote__c where Id = :quoteId];
            // Add the account Id and existing subscription Id if they are populated on the quote object
            if (String.isNotBlank(quote.zqu__ZuoraAccountId__c)) quoteContextParams.put('billingAccountId', quote.zqu__ZuoraAccountId__c);
            if (String.isNotBlank(quote.zqu__ExistSubscriptionId__c)) quoteContextParams.put('subscriptionId', quote.zqu__ExistSubscriptionId__c);   
            return zqu.QuoteWizardManager.navigateback(quoteContextParams);
        // If the current page is NOT part of the Quote Wizard, return to the Quote List page.
        return Page.zqu__QuoteList;


Implement the HostedPageLiteGoNextPlugin to add custom logic when user navigates to the next page. 

Method Signature: PageReference navigateNext(String paymentMethodType, Map < String, String > callbackParameters)

Default Implementation: zqu.PaymentPageController.DefaultHostedPageLiteGoNextPlugin

The callbackParameters argument is a key-value mapping of callback parameter names to their corresponding values. callbackParameters contains the following keys:

  • success: Status of Payment Page submission
  • errorCode: Error code returned when Payment Page callback fails
  • errorMessage: Error message to display if the Payment Page callback fails
  • refId: ID of the Payment Method created
  • accountId: ID of the Zuora account determined by the 'field_accountId' value returned in the IHostedPageLitePlugin
  • quoteId: ID of the current quote
  • Any other payment method fields configured to be returned in Zuora

Custom Go Next Plugin Example

The following custom Go Next Plugin appends the Subscription Id to the callback URL.

global class MyGoNextPlugin extends zqu.PaymentPageController.DefaultHostedPageLiteGoNextPlugin {
	global override PageReference navigateNext(String paymentMethodType, Map < String, String > callbackParameters) {
       // If the transaction was not successful, display the error message to the user
       Boolean success = Boolean.valueOf(callbackParameters.get('success'));
       if(!success) {
           String errorMessage = callbackParameters.get('errorMessage');
           ApexPage.addMessage(new ApexPages.Message(ApexPages.Severity.ERROR, errorMessage));
           return null;

		// Get the page returned by the parent class
		PageReference nextPage = super.navigateNext(callbackParameters);

		// Add a custom URL parameter
		nextPage.getParameters().put('subscriptionId', '2c92c0f949a46f5f0151a5852a2e6c87');

		// Return the result
		return nextPage;


Implement the HostedPageLitePlugin to provide values for the client parameters and pre-populated values on the Payment Page. You construct and return a map of key-value pairs in which the keys are the names of the Payment Page client parameters and form fields. The return values are added to the client parameters and passed into the Z.render function.

Client parameter values this plugin returns override the default values on the Payment Page.

The default client parameter values are determined as follows:

  • tenantId, token, signature, key: From the Zuora tenant the Salesforce org is linked to
  • id: The zuoraPageId attribute of the Payment Page component
  • style: The style attribute of the Payment Page component
  • submitEnabled: The submitEnabled attribute of the Payment Page component
  • url: The URL from which your Payment Page will be served, e.g. 
  • paymentGateway: Payment gateway of the quote, if supplied

The default implementation of the HostedPageLitePlugin populates the creditCardAddress1, creditCardCountry and creditCardState fields on the Payment Page with the MailingStreet, MailingCountry and MailingState fields of the billing contact associated with the current quote.

The current quote is determined by the "id" parameter in the URL. If the id of a zqu__Quote__c object is not specified in the URL, or if the quote is not associated to a billing contact, the fields will not be pre-populated.

This plugin also populates the "field_accountId" of the Payment Page with the value of zqu__ZuoraAccountId__c of the current quote.

Method Signature: Map < String, String > getAdditionalParameters(String paymentMethodType)

Default Implementation: zqu.PaymentPageController.DefaultHostedPageLitePlugin​

Custom Default Value Plugin Example

The following custom Default Values Plugin pre-populates Payment Page fields. The Payment Method Type of the current Payment Page determines the fields pre-populated with default values. There are three different payment method types defined by the following constants:

Payment Method Type Constant
Credit Card zqu.PaymentPageController.PAYMENT_METHOD_TYPE_CREDIT_CARD
ACH zqu.PaymentPageController.PAYMENT_METHOD_TYPE_ACH
Bank Transfer zqu.PaymentPageController.PAYMENT_METHOD_TYPE_BANK_TRANSFER
global class MyDefaultValuePlugin implements zqu.PaymentPageController.IHostedPageLitePlugin {
	global Map < String, String > getAdditionalParameters(String paymentMethodType) {
		Map < String, String > defaultValues = new Map < String, String >();
        // Set the default values for payment method type credit card
        if(paymentMethodType == zqu.PaymentPageController.PAYMENT_METHOD_TYPE_CREDIT_CARD) {
            defaultValues.put('creditCardAddress1', '999 3rd Ave');
            defaultValues.put('creditCardAddress2', 'Unit 7');
            defaultValues.put('creditCardCity', 'San Mateo');
            defaultValues.put('email', '');
        // Set the default values for payment method type ACH
        else if(paymentMethodType == zqu.PaymentPageController.PAYMENT_METHOD_TYPE_ACH) {
            defaultValues.put('achBankAccountType', 'Checking');
            defaultValues.put('achBankAccountName', 'John Doe');
        // Set the default values for payment method type Bank Transfer
        else if(paymentMethodType == zqu.PaymentPageController.PAYMENT_METHOD_TYPE_BANK_TRANSFER) {
            defaultValues.put('streetNumber', '999');
            defaultValues.put('streetName', '3rd Ave');
            defaultValues.put('city', 'San Mateo');
        // Default client parameters
        defaultValues.put('field_accountId', '2c92c0f84abe7d45014ac0e2d35e1234');
        defaultValues.put('retainValues', 'true');

		return defaultValues;

When you navigate to the Payment Page, you will see the Payment Page form pre-populated with the default values specified in MyDefaultValuePlugin.