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.
This section describes how to configure a Hosted Payment Method page in the Zuora application.
Configure Hosted Payment Method Page
Before any integration work can begin, the hosted page must be set up within Zuora.
To create a Hosted Payment Method page:
- In Zuora, browse to Settings >Payments, and click Setup Hosted Pages.
- Select a Type of payment. Available options are Credit Card, Bank Transfer-ACH, and Bank Transfer-Direct Debit(UK).
- Click create new hosted page.
- In the Basic Information section, enter the following information.
- Name: Enter a name for your page. This name is used to identify your page in Zuora. It is different from the title displayed on the page that you specify in the PageTitle field.
- Hosted Domain: Specify the domain name on which your callback file resides. It should be in the format: http://www.domain.com (or https://www.domain.com).
The Hosted Domain address must match the domain of the webpage that is accessed in order to use the submit button. For example, if the domain is configured as http://www.domain.com but you submit the hosted page on http://domain.com, the submission will not work. The hosted page can only be submitted if the user accesses http://www.domain.com.
- Callback Path: Enter the path on which the callback 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. There is no requirement to include a file extension (for example,
.php) for the callback path. However, the callback path must begin with a forward slash character (
/) character, as shown above.
- In the Payment Gateway section, enter the following information:
- Payment Gateway: Select a payment gateway to use. The gateway must be configured in your Zuora environment. Note that Zuora does not validate this setting.
- If this page is of the Bank Transfer-Direct Debit payment type, the Country fields appear. Currently, only United Kingdom is supported in the Country field.
- In the Page Configuration section, enter the following information.
- Page Title: Enter a title for the page (optional). Select Enabled to display Page Tile on this Hosted Payment Method page.
- Page Description: Enter a description for the page (optional). Select Enabled to display Page Description on this Hosted Payment Method page.
- For each field in the Page Fields section:
- Enabled: Select to display the field.
- Required: Select to make this field a require field.
- Label Name: Enter the display label to be shown on this hosted page.
- 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 input field sections, in the order field next to the section, enter the number representing the display order of the field section on this hosted page.
- Credit Card Validation: If you are configuring a Credit Card type Hosted Payment Method page, select Enable client-side credit card validation to validate input credit card number and to auto-select credit card type at run-time. See Client-Side Credit Card Validation for validation detail.
- If you select Enable client-side credit card validation, optionally specify customized error messages in the Invalid Card Number and Invalid Card Type fields.
- If you select Enable client-side credit card validation, but do not specify error messages, no error message will be displayed when an invalid card number or invalid card type is entered. The credit card number field will be highlighted with a red border.
- CSS: Enter the custom CSS code for your page. Instructions about modifying the CSS can be found at Hosted Payment Method pages CSS.
- Click generate and save page.
- The Preview Hosted Payment Method page shows the page as it would be displayed on your website. Click edit to make any changes to the page.
- The preview page includes sample HTML code. You can embed this code in your website to test how the Hosted Payment Method pages would look in your checkout flow.
Client-Side Credit Card Validation
Credit Card Validation
When you enable the client-side credit card validation via the Enable client-side credit card validation check box, the following checks are performed as user enters a credit card number on the Hosted Payment Method 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 actually check-sum?
For example, the input credit card number must check-sum to make it an valid AMEX card number. It cannot be random 13 numbers that begins with "34".
The error messages that you specified while enabling the client-side validation are displayed in red, and the credit card number field is highlighted with a red border.
Automatic Selection of Credit Card Type
When you enable the client-side credit card validation via the Enable client-side credit card validation check box, the credit card type will be automatically selected.
As user enters a credit card number on the Hosted Payment Method page, the credit card type is automatically identified based on user's entry, and the credit card logo is displayed in foreground. Supported credit card types are AMEX, Visa, Discover, and MasterCard.
Note: If you would like to accept additional card types, such as JCB or Diners Club, we recommend not enabling client-side credit card validation.
If user enters a credit card number of an unsupported or unrecognized card type, an error message will be displayed.