Skip to main content

Configure Bank Transfer type Payment Pages 2.0


Configure Bank Transfer type Payment Pages 2.0

This article describes how to configure Payment Pages 2.0 to enable your customers to create payment methods of the Bank Transfer type. For details about compatibility with the browsers, see Browser Support Policy.


Create a Payment Page for Bank Transfer type

Before any integration work can begin, set up a Payment Page 2.0 in Zuora:

  1. Navigate to Settings > Payments, and click Setup Payment Page and Payment Link.
  2. On the Payment Pages tab page, configure the tenant-level settings for the hosted payment page.
  3. In the Type dropdown list, select one of the following Bank Transfer types:
    • Bank Transfer - ACH
    • Bank Transfer - Direct Debit (NZ)
    • Bank Transfer - PAD (CA)
    • Bank Transfer - Direct Debit (UK)
    • Bank Transfer - Direct Entry (AU)
    • Bank Transfer - Autogiro
    • Bank Transfer - SEPA
    • Bank Transfer - Betalingsservice
  4. Click create new hosted page.
  5. In the Basic Information area, enter the following information:
    • Page Name: Type a name for your Payment Page form. This name is used to identify your form in Zuora. It is different from the title displayed on the form. You specify the form title in the Page Title field in the Page Configuration section.
    • Hosted Domain: Type the domain address from which your Payment Page will be served. This is also the domain where your callback page resides. The value should be in the format: Zuora validates this field for you. You will see an error message displayed on HPM iframe if the validation fails.

      To allow your hosted payment pages and callback pages to reside in the subdomain of the hosted domain, enable the Allow Subdomain Callback for Hosted Pages setting. See Configure Payment Pages 2.0 for details.

      Note that the Overlay Hosted Page mode does not support the Hosted Domain validation.

    • Callback Path: Type the path on which the callback page file resides. Zuora appends this to the Hosted Domain entry to create the full URL to which the callback is sent. Specify a value in the format: /app/callback_file.jsp. You are not required to include a file extension, for example, .jsp or .php. However, the callback path must begin with a forward slash character ( / ).
      The Callback Path is only required when you are using the advanced implementation option, using the inline style form with an external submit button. The Callback Path setting is ignored when you implement the basic setup, i.e., using the overlay form or the inline form with the submit button inside.
  6. In the Security Information area, configure the page-level security settings. For detailed information about each option, see Security Measures for Payment Pages 2.0.
  7. In the Payment Gateway area, enter the following information:
    • Default Payment Gateway: Click and select a payment gateway to use. The gateway must be configured in your Zuora environment. Note that Zuora does not validate this setting. You can override this default gateway in your request by specifying a gateway through the paymentGateway client parameter.
    • (Optional)Country: This field is only available if you select the Bank Transfer - Direct Debit (UK) type Payment Page. Only United Kingdom is supported for this field.
  8. In the Page Configuration area, complete the field configuration. 
    • Page Title: Enter a title for the Payment Page form. Select Display to display the Page Title on this Payment Page form.
    • Page Description: Enter the description of the form. Select Display to display the Page Description on this Payment Page form.
    • For each field in the Page Fields section, complete the following configuration. For more information about the fields, see Payment Pages 2.0 form fields.
      • Label Name: Enter the display label to be displayed on this Payment Page.
      • Display: Select to display the field on the Payment Page.
      • Required: Select to make the field a required field.

        Because the required fields for different gateways and different bank transfer schemes vary, you should check your gateway documentation to determine which fields are required.

      • If you want to change the default display order of the input fields within a section, such as in the Bank Account Information or Customer Information section, enter the number representing the display order of the field within the section.
      • If you want to change the display order of the sections, in the order field next to the section, enter the number representing the display order of the section on this Payment Page.
    • Submit Button: Enter the label to appear on the submit button. This label is applied only if the button is on the Payment Page form. See Client Parameters for Payment Pages 2.0 for the parameter, submitEnabled, that controls the placement of the submit button.
      • If submitEnabled is set to true, the Submit button is enabled on your Payment Page when the user selects the Agreement Checkbox field.
      • If submitEnabled is set to false, you can use Zuora JavaScript function to control the event when the user selects the Agreement Checkbox field.
    • Client-Side Validation: Select Enable client-side validation to check the required fields for values.
      • If the client-side validation is enabled, you can specify a custom error message for missing required fields in the Error Message field.
      • In the Error Message field, use "#fieldName" to include the missing field name in the error message. For example, "Please enter a valid #fieldName to continue."
    • Confirmation Dialog: Select Enable Confirmation Dialog to add a step to display a confirmation dialog in the Payment Page workflow. When this step is enabled, your customers get a chance to confirm the information they entered before submitting the payment method.

      When you select Enable Confirmation Dialog, the template editor appears. Customize the Confirmation Dialog by typing in the desired information in the template editor, such as the page heading, your merchant name, etc. If you want to customize the displayed fields, see Reference Bank Transfer form fields in confirmation dialogs. If you want to customize the CSS style of the Confirmation Dialog, add the customized CSS to the CSS field. The default behavior of the Cancel button is closing the confirmation dialog and allowing the end user to edit the account information again. If you want to customize the logic, you can use the onCancelMandatePage event handler in your client code.

    • For the bank transfer type of hosted payment pages on GoCardless, a Retrieve Mandate PDF setting is available below Enable Confirmation Dialog. With this setting enabled, the confirmation dialog contains all the required consent information and a link to the mandate PDF file. See Mandate PDF setting specific for GoCardless for more information.

    • CSS: Enter the custom CSS code for your page. You can review the CSS id and class names by using View Source or Inspect Element in Firefox or Chrome on the preview page of this Payment Pages form. For example, you can customize the style and format of the field label and error message, as well as the error message texts. However, implementing customized JavaScript is not allowed for security reasons.

      Design Payment Pages CSS provides a CSS pack that you can download and use to design the look and formatting of your Payment Pages 2.0 form.

      Ensure that you enter the valid CSS codes in this field. An error will occur if you include HTML tags or other invalid characters.

  9. Click generate and save page.

Subsequently, you can preview Payment Pages 2.0 to preview the form that will be displayed on your website. 

Mandate PDF setting specific for GoCardless

For the bank transfer type of payment pages on GoCardless, when creating a new payment page, select Retrieve Mandate PDF in the Confirmation Dialog section to meet GoCardless’ implementation requirements for scheme compliance, which requires the ability for end users to view and download the mandate at the time it is being generated. With this setting selected, Zuora retrieves the dynamic link of the mandate PDF file from the GoCardless gateway. The confirmation dialog will contain all the required consent information and a link to the mandate PDF file for end users to download. It is recommended to review the confirmation dialog template first and then make further updates to the template for your needs.

For the existing bank transfer type of payment pages on GoCardless, in addition to enabling the Retrieve Mandate PDF setting, add the following code to your confirmation dialog template:

  • In the HTML section, add the following code to a position according to the design of your confirmation dialog layout. For example, you can add the following code in front of the code block for the confirmation button:
    <div class="section">
        <a class="mandate_pdf_download">Mandate PDF can be downloaded here</a>
  • In the CSS section, add the following code within the <style> </style> tag:
    .mandatePage .mandate_pdf_download {
    color: #50AFB1;

The Retrieve Mandate PDF setting is only available for bank transfer type of payment pages on GoCardless.