Payment Pages 2.0 Form Fields

Knowledge Center > Billing and Payments > Hosted Payment Pages > Payment Pages 2.0 > Payment Pages 2.0 Form Fields

Payment Pages 2.0 Form Fields

This article lists the fields on the Payment Pages 2.0 configuration page.  When you pre-populate the form fields or access a form field value in a callback function, use the field names given in this article to reference the fields. See Integrate Payment Pages 2.0 for referencing form fields in a callback function. See below for pre-populating form fields.

Payment Pages 2.0 Form Fields

Credit Card Type Fields

Field Name
(case sensitive)
Default Field Label Type Maximum Length Allowed Values
creditCardExpirationMonth Expiration Date (YYYY) String 2 "1" through "12"
creditCardExpirationYear   String 4  
creditCardType Card Type String 20
  • Visa
  • MasterCard
  • AmericanExpress
  • Discover
creditCardNumber Card Number String 32  
cardSecurityCode CVV String 4  
creditCardHolderName Cardholder Name String 50  
creditCardCountry Country String 3 3-digit ISO code
creditCardState State String 50 State or province
creditCardAddress1 Address 1 String 255  
creditCardAddress2 Address 2 String 255  
creditCardCity City String 40  
creditCardPostalCode Postal Code String 20  
ipAddress N/A String 80

The IP address of the user when the payment method was created or updated. Some gateways use this field for fraud prevention. 

Payment Pages only support IPv4 addresses.

This field is hidden and does not appear on the form.

phone Contact Phone Number String 40  
email Email Address String 80  

Bank Transfer - ACH Type Fields

Field Name
(case sensitive)

Default Field Label


Maximum Length

Allowed Values


ABA/Routing Number



achBankAccountNumber Bank Account Number String 40  
achBankAccountType Account Type String 50
  • Checking
  • Saving
  • BusinessChecking

In the Payment Pages 2.0 configuration UI, the pick list option appears as "Business Checking", but when you specify this value in the client code, you need to use "BusinessChecking" without a space.

achBankName Bank Name String 150  
achBankAccountName Account Holder Name String 150  
achCity Ach City String 40  
achState Ach State String 50  
achCountry Ach Country String 64  
phone Contact Phone Number String 32  
email Contact Email String 255  
achPostalCode Ach Postal Code String 20  
achAddress1 ACH Address 1 String 255  
achAddress2 ACH Address 2 String 255  

Bank Transfer - Direct Debit (UK) Type Fields

Field Name
(case sensitive)
Default Field Label  Type  Maximum Length Allowed Values
agreement_checkbox Agreement Checkbox Checkbox N/A  
bankAccountNumber Account Number String 30  
bankAccountName Account Name String 30  
bankCode Bank Code  String  9  
bankName Bank Name  String  40   
firstName First Name  String 15   
lastName Last Name  String 35   
streetNumber Street Number  String 15   
streetName Street Name  String 50   
city City  String 40   
state State  String 35   
postalCode Postal Code  String 10   
email E-mail String  255  
mandateReceivedStatus Mandate Received  Boolean  1
  • Yes
  • No
existingMandateStatus Existing Mandate  Boolean  1
  • Yes
  • No
mandateId Mandate ID  String 18   
mandateCreationDateDay Creation Date  Integer  2  
mandateCreationDateMonth Creation Date  Integer  2  
mandateCreationDateYear Creation Date  Integer  4  
mandateUpdateDateDay Update Date  Integer  2  
mandateUpdateDateMonth Update Date  Integer  2  
mandateUpdateDateYear Update Date  Integer  4  

Bank Transfer - SEPA Type Fields

Field Name
(case sensitive)
Default Field Label  Type  Maximum Length Comments
bankAccountNumber Account Number String 30 This is the IBAN.
businessIdentificationCode Business Identification Code String 11  
bankAccountName Account Name String 30  
bankName Bank Name String 40  
bankStreetNumber Bank Street Number String 10  
bankStreetName Bank Street Name String 35  
bankCity Bank City String 35  
bankPostalCode Bank Postal Code String 10  
firstName First Name String 15  
lastName Last Name String 35  
streetNumber Street Number String 15  
streetName Street Name String 50  
email Email Address String 80  
city City String 40  
state State String 35 State or province
postalCode Postal Code String 10  
country Country String - 3-digit ISO code
mandateReceivedStatus Mandate Received Boolean -
  • Yes
  • No
existingMandateStatus Existing Mandate Boolean -
  • Yes
  • No
mandateId Mandate ID String 18  
mandateCreationDateDay Creation Date Integer 2  
mandateCreationDateMonth Creation Date Integer 2  
mandateCreationDateYear Creation Date Integer  4  
mandateUpdateDateDay Update Date Integer 2  
mandateUpdateDateMonth Update Date Integer 2  
mandateUpdateDateYear Update Date Integer 4  

Pre-populate Payment Pages 2.0 Form Fields

Most of the input fields on Payment Pages 2.0 forms are available for pre-population for all types of payment methods. In your client code, provide field-value pairs in a JavaScript object and pass them to the Z.render function. The following is a sample code that specifies the five credit-card related fields to be pre-filled with the given values.

var prepopulateFields = {
   creditCardAddress1:"123 Any Street",
   creditCardAddress2:"Suite #999",
   creditCardHolderName:"John Doe"

If you do not want to pre-populate any field in your Payment Page form, declare an empty set, and pass it to Z.render function. For example:

var prepopulateFields = {}

Encrypt to Pre-popluate Restricted Fields

For Payment Card Industry (PCI) compliance and other data security, the restricted fields are required to be encrypted in order for the field values to be pre-populated on Payment Pages.
If you are using the Payment Pages 2.0 JavaScript library of version 1.2.0 or higher, the following fields must be encrypted on Payment Pages of the of the Credit Card type:
  • creditCardNumber
  • cardSecurityCode: CVV
  • creditCardExpirationYear
  • creditCardExpirationMonth
If you are using the Payment Pages 2.0 JavaScript library of version 1.3.0 or higher, in addition to the above fields, the following field must be encrypted on Payment Pages:
  • ipAddress for the Credit Card type
    Use the field only if you want to send the IP address back to Zuora for the fraud prevention purpose. Payment Pages 2.0 only supports IPv4 addresses.
  • bankAccountName for the SEPA and Direct Debit (UK) types
  • bankAccountNumber for the SEPA and Direct Debit (UK) types

If the above restricted field values are not encrypted, the fields are not going to be pre-populated in Payment Pages 2.0 forms, and the values are not sent to Zuora. You get an alert to inform that these fields need to be encrypted. For the users who do not use Microsoft Internet Explorer, an error is also logged in the JavaScript console. 

Use the RsaEncrypter.encrypt java function defined in the Zuora security library to encrypt the above restricted fields. Include the following line in your Java code to use RsaEncrypter.encrypt:


The below code is a sample implementation of an encryption function. You can also find the sample encryption code in Payment Pages 2.0 Sample Code Repository.


for(Iterator<String> iterator = prepopulateFields.keySet().iterator(); iterator.hasNext(); ) {    
   private static final Set<String> fieldToEncrypt = new HashSet<String>();
   static {

String key =;
String value = prepopulateFields.get(key);
if(fieldToEncrypt.contains(key)) {
   value = RsaEncrypter.encrypt(value, publicKeyString);
   // For zuora.js version 1.2.0 and later, PCI pre-populate fields are in prepopulateFields.
   prepopulateFields.put(key, value);

Cookie Handling

For the inline style with the submit button outside, Payment Pages will keep user's values in cookie only if both of the following conditions satisfy:

  • The tenant-level permission, Disable HPM Cookies, is NOT enabled.
  • The retainValues parameter is set to true.

In all other cases, the values users enter in Payment Page form will not be cached.

The following requirements must satisfy for the retainValues to correctly work:

  • This parameter is used only for the inline style Payment Pages 2.0 forms with the external submit button.
  • The retainValues should be used only for the Payment Pages forms that are reloaded after an unsuccessful submission. The first loading of the Payment Page form should not include the retainValues parameter.
Last modified



(not set)