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 fields
Field Name (case sensitive) |
Default Field Label | Type | Maximum Length | Allowed Values | Notes |
---|---|---|---|---|---|
creditCardExpirationMonth | Expiration Date (YYYY) | String | 2 | "1" through "12" | |
creditCardExpirationYear | String | 4 | |||
creditCardType | Card Type | String | 20 |
|
|
creditCardNumber | Card Number | String | 32 | Although a maximum of 32 characters are allowed in this form field, Zuora only supports 13-16 digit card numbers. | |
cardSecurityCode | CVV | String | 4 | ||
creditCardHolderName | Cardholder Name | String | 50 | 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 | ||
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 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 |
Default Field Label |
Type |
Maximum Length |
Allowed Values | Notes |
---|---|---|---|---|---|
achBankABACode |
ABA/Routing Number |
String |
9 |
||
achBankAccountNumber | Bank Account Number | String | 40 | ||
achBankAccountType | Account Type | String | 50 |
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 | 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 | This field is added in the R220 release. To add this field to the hosted page, re-create the page. | |
achState | Ach State | String | 50 | This field is added in the R220 release. To add this field to the hosted page, re-create the page. | |
achCountry | Ach Country | String | 64 | This field is added in the R220 release. To add this field to the hosted page, re-create the page. | |
phone | Contact Phone Number | String | 32 | ||
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 | Required. This is the IBAN. |
bankAccountName | Account Name | String | 30 | Required. |
bankCode | Bank Code | String | 9 | 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 | |
String | 255 | |||
mandateReceivedStatus | Mandate Received | Boolean | 1 |
|
existingMandateStatus | Existing Mandate | Boolean | 1 |
|
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 | Required. This is the IBAN. |
businessIdentificationCode | Business Identification Code | String | 11 | |
bankAccountName | Account Name | String | 30 | 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 Address | String | 80 | ||
city | City | String | 40 | |
state | State | String | 35 | State or province |
postalCode | Postal Code | String | 10 | |
country | Country | String | - |
Required for transactions through Stripe v2 for certain countries |
mandateReceivedStatus | Mandate Received | Boolean | - |
|
existingMandateStatus | Existing Mandate | Boolean | - |
|
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 | Required. 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. |
bankAccountName | Account Name | String | - | |
bankName | Bank Name | String | - | |
bankCode | Bank Code | String | 5 | Required. This is the transit number. |
bankBranchCode | Branch Code | String | 3 | Required. This is the institution number. |
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 | |
String | 255 | Required. This email is used for the verification of micro-deposits if Stripe verification is enabled. | ||
mandateReceivedStatus | Mandate Received | Boolean | - |
|
existingMandateStatus | Existing Mandate | Boolean | -
|
|
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
- creditCardNumber
- cardSecurityCode: CVV
- creditCardExpirationYear
- creditCardExpirationMonth
- 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 totrue
.
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 theretainValues
parameter.