Skip to main content

Payment Pages 2.0 Form Fields

Zuora

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 other functions, use the field names given in this article to reference the fields.

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

 

Payment Pages 2.0 Form Fields

Credit Card fields

Field Name
(case sensitive)
Default Field Label Type Maximum Length Allowed Values Notes
creditCardExpirationMonth Expiration Date String 2 "1" through "12" Zuora recommends making this field required.
creditCardExpirationYear   String 4   Zuora recommends making this field required.
creditCardType Card Type String 20
  • Visa
  • MasterCard
  • AmericanExpress
  • Discover
Zuora recommends making this field required.
creditCardNumber Card Number String 32  

Zuora recommends making this field required.

Although a maximum of 32 characters are allowed in this form field, Zuora only supports 13-16 digit card numbers.

cardSecurityCode CVV String 4   Zuora recommends making this field required.
creditCardHolderName Cardholder Name String 50  

Zuora recommends making this field required.

For the integration with the CyberSource gateway, when passing this field to the gateway, the string value of this field is split into first name and last name with the first space in the string.

creditCardCountry Country String 3

3-digit ISO code

For a complete list of supported ISO country codes, see View countries or regions.

 
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  

The maximum length and allowed values for this field vary by payment gateways. To find out the specific requirements, use the following methods:

  • Refer to the documentation of the gateway provider.
  • Use the information in the response message. If field validation fails on the gateway side, the gateway provider will return a message that might include the length and value requirements for this field.
ipAddress N/A String 128

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

Both IPv4 and IPv6 are supported.

This field is hidden and does not appear on the form.
phone Contact Phone Number String 40    
email Email Address String 80    
identityNumber Identity Number String 20

 

This field is used to capture the Tax Identification Numbers (For example, CPF/CNPJ in Brazil) of end customers in Latin America.

When configuring the payment page, you can customize the field label of Identity Number for better clarity. For example, update the field label to CPF/CNPJ Number for your Brazilian customers.

The following gateway integrations support using this field to capture the Tax Identification Numbers:

Note that if you collect payments in Latin America, the best practice is to set this field as a mandatory field in your payment page to ensure this information is always collected.

Bank Transfer

ACH fields

Field Name
(case sensitive)

Default Field Label

Type

Maximum Length

Allowed Values Notes

achBankABACode

ABA/Routing Number

String

9

  Zuora recommends making this field required.
achBankAccountNumber Bank Account Number String 40   Zuora recommends making this field required.
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.

Zuora recommends making this field required.
achBankName Bank Name String 150   Zuora recommends making this field required.
achBankAccountName Account Holder Name String 150  

Zuora recommends making this field required.

For hosted Payment Pages on the BlueSnap integration, see Overview of BlueSnap gateway integration for more information about how Zuora splits the string in this field into two parts and passes them to BlueSnap's firstName and lastName fields.

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   This field is added in the R220 release. To add this field to the hosted page, re-create the page.
achAddress1 ACH Address 1 String 255    
achAddress2 ACH Address 2 String 255    
ipAddress N/A String 128

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

Both IPv4 and IPv6 are supported.

This field is hidden and does not appear on the form.
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    

Direct Debit (UK) fields

Field Name
(case sensitive)
Default Field Label  Type  Maximum Length Notes
agreement_checkbox Agreement Checkbox Checkbox N/A  
bankAccountNumber Account Number String 35

This is the IBAN.

Zuora recommends making this field required.

bankAccountName Account Name String 30 Zuora recommends making this field required.
bankCode Bank Code String  9 Zuora recommends making this field required.
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  

SEPA fields

Field Name
(case sensitive)
Default Field Label  Type  Maximum Length Notes
bankAccountNumber Account Number String 35

This is the IBAN.

Zuora recommends making this field required.

businessIdentificationCode Business Identification Code String 11  
bankAccountName Account Name String 30 Zuora recommends making this field required.
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 Required for transactions through Stripe v2 for certain countries
streetName Street Name String 50 Required for transactions through Stripe v2 for certain countries
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

For a complete list of supported ISO country codes, see View countries or regions.

Required for transactions through Stripe v2 for certain countries

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  
ipAddress N/A String 128

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

Both IPv4 and IPv6 are supported.

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

PAD fields

Field Name
(case sensitive)
Default Field Label Type Maximum Length Notes
bankAccountNumber Account Number String 12

This is the account number. 7-12 characters are allowed. If the account number is less than 7 characters, prepend the account number with zeros in front of the string to get the account number to 7 characters.

Zuora recommends making this field required.

bankAccountName Account Name String -  
bankName Bank Name String -  
bankCode Bank Code String 5

This is the transit number.

Zuora recommends making this field required.

bankBranchCode Branch Code String 3

This is the institution number.

Zuora recommends making this field required.

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 email String 255

This email is used for the verification of micro-deposits if Stripe verification is enabled.

Zuora recommends making this field required.

mandateReceivedStatus Mandate Received Boolean -
  • Yes
  • No
existingMandateStatus Existing Mandate Boolean -

 

  • Yes
  • No
mandateId Mandate ID String -  
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  

Reference Bank Transfer form fields in confirmation dialogs

If the Confirmation Dialog feature is enabled for your Bank Transfer payment page, after the payment page submission, a confirmation dialog is displayed for your customers to review and confirm the information they entered. The template editor for the confirmation dialog contains default fields that are displayed in the dialog. You can customize the displayed fields for general account information, such as account number, account name, bank code, and address information, by using the field mappings provided in the preceding tables. To reference a specific field in the template editor, use the format "field_<Field_Name>". For example, use field_bankCode to reference the bankCode field.

Here is an example of adding account number, account name, and bank code to the confirmation dialog:

<div class="field">
    <div class="label">account number: </div>
    <div class="value">{{field_bankAccountNumber}}</div>
</div>
<div class="field">
    <div class="label">account name: </div>
    <div class="value">{{field_bankAccountName}}</div>
</div>
<div class="field">
    <div class="label">bank code: </div>
    <div class="value">{{field_bankCode}}</div>
</div>

Pre-populate Payment Pages 2.0 Form Fields

Input fields displayed 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. Pre-population is not supported for hidden fields.

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",
   creditCardCountry:"USA",
   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 = {}
...
 Z.render(
      params,
      prepopulateFields,
      callback
 );

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. Both IPv4 and IPv6 are supported.
  • 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:

import com.zuora.rsa.security.encrypt.RsaEncrypter

The below code is a sample implementation of an encryption function. You can also find the sample encryption code in the Payment Pages 2.0 sample code suite on Zuora GitHub site.

import com.zuora.rsa.security.encrypt.RsaEncrypter;

for(Iterator<String> iterator = prepopulateFields.keySet().iterator(); iterator.hasNext(); ) {    
   private static final Set<String> fieldToEncrypt = new HashSet<String>();
   static {
      fieldToEncrypt.add("creditCardNumber");
      fieldToEncrypt.add("cardSecurityCode");
      fieldToEncrypt.add("creditCardExpirationYear");
      fieldToEncrypt.add("creditCardExpirationMonth");
}

String key = iterator.next();
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.