Hosted Payment Method Page Fields
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.
Overview
This page lists the fields that can be appended to the Hosted Payment Page URL to add functionality.
Field Prefixes
Add the following prefixes to the fields when you append the fields to the URL:
field_
: Use thefield_
prefix to pre-populate the values of these fields when the iframe is loaded.error_
: Use theerror_
prefix to indicate the fields having errors when the response is sent back from Zuora service. For example,error_cardSecurityCode
can be a URL parameter passed back from Zuora indicating there is an error on thecardSecurityCode
field.
For setting input fields with the values entered from your website, do not use the field_
or error_
prefix on field names. For example, if you want the subscriber's address to be copied to the Bill-to address in the Hosted Payment Method iFrame, the field referenced is creditCardAddress1
not field_creditCardAddress1
.
Payment Method Fields
Field Name (case sensitive) |
Description |
Max Len |
---|---|---|
accountId |
The Zuora system account ID of the contact with which this payment method is associated. |
32 |
deviceSessionId |
The (web) session ID of the user when the PaymentMethod was created or updated. This is used for fraud prevention with some gateways. If passed to Zuora, Zuora will pass this field to supported gateways. Currently, only Verifi supports this field. |
255 |
ipAddress |
The IP address of the user when the PaymentMethod was created or updated. This is used for fraud prevention with some gateways. If passed to Zuora, Zuora will pass this field to supported gateways. Currently, only PayPal, CyberSource, Authorize.Net, Verifi, Worldpay, and Allpago support this field. |
15 |
useDefaultRetryRule |
Set this to If you set this to |
5 |
paymentRetryWindow |
Use the retry interval setting to prevent a payment attempt if the last failed payment was within the specified number of hours. For example, if the last failed payment was at 1PM and the retry interval is 4 hours, then a payment run at 2PM will not attempt a payment, but a payment run at 6PM will. If you want to retry once a day, Zuora recommends that you enter 22 or 23 hours, because it is possible for a payment to be attempted at the end of the payment run on one day and the beginning of the payment run the next day. This field is required if |
6 |
maxConsecutivePaymentFailures |
Specifies the number of allowable consecutive failures Zuora will make with the payment method before stopping. |
6 |
Credit Card Type Fields
Field Name (case sensitive) |
Possible Values |
Max Len |
---|---|---|
creditCardType supportedTypes |
Visa, MasterCard, AmericanExpress, Discover |
20 |
creditCardNumber1 |
string |
16 |
creditCardExpirationMonth1 |
integer |
2 |
creditCardExpirationYear1 |
integer |
4 |
cardSecurityCode1 |
string |
4 |
creditCardHolderName |
string |
50 |
creditCardCountry |
32 |
|
creditCardAddress1 |
string |
255 |
creditCardAddress2 |
string |
255 |
creditCardCity |
string |
40 |
creditCardState |
string |
50 |
creditCardPostalCode |
string |
20 |
phone |
string |
40 |
|
string |
80 |
ACH Type Fields
Field Name (case sensitive) |
Possible Values |
Maximum Length |
---|---|---|
achBankABACode |
string |
9 |
achBankAccountNumber | string | 40 |
achBankAccountType | Checking, Savings | 50 |
achBankName | string | 150 |
achBankAccountName | string | 150 |
phone | string | 32 |
string | 255 |
Bank Transfer Fields
Field Name (case sensitive) | Possible Values | Max Len |
---|---|---|
bankAccountNumber | String | 30 |
bankAccountName | String | 30 |
bankCode | String | 9 |
bankName | String | 40 |
bankBranchCode | String | 5 |
bankCheckDigit | String | 2 |
bankStreetNumber | String | 10 |
bankStreetName | String | 35 |
bankCity | String | 35 |
bankPostalCode | String | 10 |
businessIdentificationCode | String | 10 |
firstName | String | 15 |
lastName | String | 35 |
streetNumber | String | 15 |
streetName | String | 50 |
city | String | 40 |
state | String | 35 |
postalCode | String | 10 |
String | 80 | |
country | String | 2 |
IBAN | String | 21 |
mandateReceivedStatus | Yes, No | 1 |
existingMandateStatus | Yes, No | 1 |
mandateId | String | 18 |
mandateCreationDateDay | Integer | 2 |
mandateCreationDateMonth | Integer | 2 |
mandateCreationDateYear | Integer | 4 |
mandateUpdateDateDay | Integer | 2 |
mandateUpdateDateMonth | Integer | 2 |
mandateUpdateDateYear | Integer | 4 |
Additional Fields
Field Name (case sensitive) |
Possible Values |
Description |
---|---|---|
retainValues |
true, false |
Use this to preload the new page with the page with the previously entered information that was saved in the browser cookie by appending the parameter |
bankTransferType | DirectDebitUK |
Use this only for the Direct Post request pattern for Bank Transfer HPM to set the bank transfer type. |
1When pre-loading the Hosted Payment Method pages, these fields must be pre-populated with encrypted values. See Customizing Hosted Payment Method Pages for more information.