Skip to main content

Configure Credit Card Type Payment Pages 2.0


Configure Credit Card Type Payment Pages 2.0

This article describes how to configure Payment Pages 2.0 to accept the credit card type payments.

Configure Credit Card Type Payment Pages 2.0

Before any integration work can begin, the Payment Page form must be set up in Zuora. For details about compatibility with the browsers, see Browser Support Policy.

To create a Payment Pages 2.0 form:

  1. In Zuora, navigate to Settings > Payments, and click Setup Hosted Pages.
  2. (Optional) Configure the tenant-level security settings for Payment Pages.
  3. In the Type field, click and select Credit Card. See Payment Methods to learn more about the payment types.
    If your tenant has both Payment Pages 1.0 and Payment Pages 2.0 enabled, you see the Hosted Page 1.0 and Hosted Page 2.0 categories.
  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 Payment Page 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 if 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 following information. For detailed information about each option, see Advanced Security Measures for Payment Pages 2.0.  
    • Google reCAPTCHA

      • Google reCAPTCHA V2 Classic: If you have enabled reCAPTCHA v2 Classic before, this option is selected and you can continue using the v2 service and configuring the Limit the number of submissions before CAPTCHA Challenge setting. However, it is strongly recommended to switch to reCAPTCHA Enterprise for an improved bot detection experience, and to avoid failures due to exceeding the reCAPTCHA quota. After reCAPTCHA Enterprise is enabled, you can no longer switch back to reCAPTCHA v2 Classic. 

      • Google reCAPTCHA Enterprise - Interactive Test: Select this option to enable the Interactive Test mode of reCAPTCHA Enterprise service, and configure the page-level Risk Score Threshold setting for this Payment Page.

      • Google reCAPTCHA Enterprise - AI Assessment: Select this option to enable the AI Assessment mode of reCAPTCHA Enterprise service, and configure the page-level Risk Score Threshold setting for this Payment Page.
      • Disable reCAPTCHA: Select this option to disable the CAPTCHA service on your Payment Page.

      • Submit hosted page requests via DirectPOST: Select this field to utilize the current page for Direct POST submissions and prevent CAPTCHA challenges from interacting with your Direct POST requests. If this setting is not selected, your Payment Page implemented through Direct POST could experience unhandled errors.

    • Token Expiration: Configure the Limit the number of submissions before blocking submission setting by entering a threshold for the number of Payment Page submissions before Zuora blocks all subsequent requests. 

    • 3D Secure:

      • Enable 3D Secure: Select this option if you want to enable 3D Secure 1.0. This option is only available if you have contacted Zuora Global Support to enable it on your tenant. See 3D Secure for more information.

      • Enable 3D Secure 2.0: Select this option if you want to enable 3D Secure 2.0. See 3D Secure 2.0 for more information.

  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. 
  8. In the Page Configuration area, enter the following information.
    • Page Title: Type a title for the Payment Page form. Select Display to display the Page Tile on this Payment Page form.
    • Page Description: Type a description for the form. Select Display to display the Page Description on this Payment Page form.
    • For each field in the Page Fields section:
      • Label Name: Enter the display label to be shown on this Payment Page.
      • Display: Select to display the field on the Payment Page.
      • Required: Select to make the field a required field.
      • Returned in Response: Select the check box to pass the value of this input field to the callback client. See Implement the Callback Function for accessing the form field value in your callback function.

        The Identify Number field is required and passed only when the country is Brazil.

        If you want to change the default display order of the input fields within a section, enter the number representing the display order of the field within the section. The below image shows an example of reordered address fields:
    • 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: Type 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.
    • Client-Side Validation: Select Enable client-side validation to validate input fields.
      For all types of Payment Pages, required fields are checked for values.
      See Client-Side Credit Card Validation for additional validation detail.
    • If you select  Enable client-side validation, optionally specify custom error messages for the credit card-related errors. Use the variable,  #fieldName, in the error message to include the missing required field name. For example, "Please enter a valid #fieldName to continue." #fieldName can only be used in the Required Field Not Completed type error message.
      You can also provide custom error messages in the optional custom error handling function.
    • Credit Card Type Detection: Select Enable automatic credit card type detection to identify the credit card type based on user's credit card number entry. Supported credit card types are AMEX, Visa, Discover, MasterCard, JCB, and Diners Club. See Automatic Detection of Credit Card Type for detail.
    • 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.

      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.

The Preview Payment Pages 2.0 page shows the page as it would be displayed on your website. 


Client-Side Credit Card Validation

Credit Card Validation

When you enable the client-side credit card validation via the Enable client-side validation check box, the following checks are performed as user enters a credit card number on the Payment Page:

  • Does the entered number match issuer's pattern? 
    For example, if the card number begins with "34" or "37", then the card is an AMEX and therefore must be 15 characters in length. If the card number beings with "4", then the card is a VISA, and the length must contain between 13 and 16 characters. 
  • Does the number checksum? 
    Credit card numbers are validated using the Luhn Algorithm for data integrity and authenticityFor example, an input credit card number must checksum to make it an valid AMEX card number. It cannot be random 13 numbers that begins with "34".
  • Does the CVV value only include numbers?
    The CVV value must only contain numbers.
  • Do all the required fields have values?

Automatic Detection of Credit Card Type

When you select the Enable automatic credit card type detection check box, the credit card type is automatically identified based on user's entry. The credit card type is automatically selected as the user enters a credit card number on the Payment Page, and the credit card logo is displayed in the foreground. Users cannot manually select the credit card type.

Supported credit card types are AMEX, Visa, Discover, MasterCard, JCB, and Diners Club.

If a user enters a credit card number of an unsupported or unrecognized card type, an error message will be displayed.

Note that with the automatic credit card type detection feature enabled, the following exceptions apply:

  • JCB card numbers will be detected as a Discover card if the card type JCB is not enabled for the configured Payment Page. 
  • Diners Club card numbers will be detected as a Discover card if the card type Diners Club is not enabled for the configured Payment Page.