Payment Pages 2.0 Form Fields

Last updated
Save as PDF

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.

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
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: Allpago BlueSnap CyberSource, Payment API v2.0 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.

Bank Transfer - 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

Bank Transfer - 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 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.

Bank Transfer - 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

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.