Client Parameters for Payment Pages 2.0
This article describes the parameters used for customizing and rendering Payment Pages 2.0.
To use the following parameters in Payment Pages 2.0, specify the parameters in a JavaScript object with key-value pairs and pass them to the Z.render function in your client.
If you include the 1.0.0 version of the Zuora JavaScript library, the values for all parameters must be URL encoded except for the url parameter. For example, "ABC DEF" must be specified as "ABC%20DEF". Even if you include the 1.0.0 version, you should not encode the url parameter.
If you include the 1.1.0 or above version of the Zuora JavaScript library library, the values are automatically encoded, and you should not encode the parameter values.
General Parameters
The following table lists the client parameters supported for all types of Payment Pages 2.0, unless otherwise specified.
| Parameter | Required? | Description |
|---|---|---|
| authorizationAmount | Optional |
The initial authorization amount. Specify a numeric value greater than 0. This value overrides the default authorization amount set for the specific payment gateway. The amount will be passed to the payment gateway to authorize the payment method in a 3DS2 transaction. The end user will not be charged unless it is a one-time payment flow for creating a payment method and processing the one-time payment transaction ( |
| checkDuplicated | Optional |
Indicates whether to perform a duplication check when you create a payment method of the following types:
The default value is With this field set to For more information, see Duplication check on payment methods. |
| countryBlackList | Optional |
List of ISO alpha-3 country codes to not be displayed from the default list of countries. If countryBlackList is used, countryWhiteList must not be used. For a complete list of supported ISO alpha-3 country codes, see View countries or regions. Example: |
| countryWhiteList | Optional |
List of ISO alpha-3 country codes to be displayed from the default list of countries. If countryWhiteList is used, countryBlackList must not be used. For a complete list of supported ISO alpha-3 country codes, see View countries or regions. Example: |
| documents | Optional |
Only available for one-time payment flows. An array of invoices to be paid in this transaction, containing the following fields:
|
| field_currency | Optional |
The currency in which the initial authorization should be done. Specify a 3-letter ISO currency code. This value overrides the default currency in the tenant when creating a payment method without a Billing Account. If field_accountId is set, then the currency on the Account is used, regardless of the value passed here. If both "field_currency" and "param_gwOptions_purchaseTotals_currency" are given, the "param_gwOptions_purchaseTotals_currency" parameter takes precedence over "field_currency." |
| field_accountId | Optional |
Zuora Id of the customer account. A payment method can be tied to a Zuora account using this parameter. When creating a payment method, it is recommended to associate the payment method with an account. |
| field_deviceSessionId | Optional |
This field is only applicable to the Verifi Global payment gateway. The session ID of the user when the Payment Method was created or updated. The gateway can use this field for fraud prevention. |
| field_gatewayName | Optional | The name of the payment gateway. Zuora recommends that you use the paymentGateway field instead. |
| field_ maxConsecutivePaymentFailures |
Optional | Specifies the number of allowable consecutive failures Zuora attempts with the payment method before stopping. |
|
field_passthrough[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15] For example, field_passthrough1, field_passthrough2, field_passthrough14 |
Optional |
Fields values to be sent back to the callback function or callback URL. Use the fields to return the information that is not captured in your Payment Pages 2.0 form to the callback function or callback URL, such as internal confirmation numbers, version test codes. etc. Due to the URL character limit of browsers, ensure that the total length of the render URL does not exceed 5,900 characters after passing in the field_passthrough parameters. Note: Though a maximum of 15 passthrough parameters can be supported when passing in your client parameters, only the first 5 parameters are used for signature generation and validation. |
| field_paymentRetryWindow | Optional | The retry interval setting, which prevents making a payment attempt if the last failed attempt was within the last specified number of hours |
| field_useDefaultRetryRule | Optional | Determines whether to use the default retry rules configured in the Payments settings. |
| id | Required | ID of the Payment Pages 2.0 form configured. Id can be obtained from the link on page list view. See Generate the Digital Signature for Payment Pages 2.0 about retrieving the form id. |
| key | Required |
Public key for encryption. The key can be generated from the configuration UI or from the See Obtain the Public Key for Payment Pages 2.0 for more information. |
| locale | Optional |
Locale ID of the Payment Pages 2.0 form, such as, "en", "fr_CA". Defaults to "en" if no corresponding resource bundle is available. See Translate and Localize Payment Pages 2.0 about uploading a resource bundle and assigning a locale to the resource bundle. |
| param_gwOptions_[option] | Optional |
Payment gateway-specific information. When the Payment Page is submitted, this option is submitted to the associated payment gateway. [option] is a gateway option for the specific payment gateway. See below for more information about these options. |
| paymentGateway | Optional |
Name of the payment gateway as set up in Payment Settings. Overrides the default gateway you set up during the Payment Page configuration. Zuora recommends that you use this field instead of the |
| retainValues | Optional |
This parameter is used only for the inline style Payment Pages 2.0 forms with the external submit button. Set to "true" to restore previously entered information to the Payment Pages 2.0 form when the form has an error upon submission. Sensitive information, such as credit card number and card security code (CVV), is not saved and is always cleared when the form is reloaded. Default is "false" which clears all the form fields upon reloading. See Error Handling for Payment Pages 2.0 for detail information about the parameter. |
| signature | Required | Digital signature generated by the rsa-signatures REST request. See Generate the Digital Signature for Payment Pages 2.0 about obtaining the signature. |
| signatureType | Optional |
Type of the digital signature generated for the callback page. Zuora supports the basic and advanced signatures for Payment Pages 2.0. Set this to "advanced" to request Zuora to generate the advanced signature in the callback response. By default the basic signature is used in the callback response. This parameter is applicable only for the advanced implementation with the Submit button outside of Payment Pages. |
| style | Required |
Rendering style of the Payment Pages 2.0 form. Allowed values are:
|
| submitEnabled | Required |
Flag to indicate that page submission is handled by Zuora or by the client site. The allowed values are:
This setting is applicable only to the inline style forms and ignored for the overlay style forms. |
| tenantId | Required | Unique ID of your Zuora tenant |
| token | Required | Token generated from the rsa-signatures REST request. See Generate the Digital Signature for Payment Pages 2.0 about obtaining the token. |
| url | Required |
Value of the Hosted Page URL field on the Payment Pages 2.0 configuration page. Even if you include the 1.0.0 version of the Zuora library, you should not encode the url value. See Preview Payment Pages 2.0 for retrieving this value. |
Gateway Options
Using the Gateway Options fields, you can submit additional information to the payment gateway associated with the Payment Page. The Payment Pages 2.0 forms can take key-value pairs to be sent as part of the gateway options when the payment method is created. Use the following format to append the key-value pairs:
param_gwOptions_[Key]:[Value]
For example, if you want to change the currency of the credit card authorization call from the default currency for the CyberSource gateway, you can set the following parameter to change the authorization request from the default currency, AUD, to JPY. CyberSource uses the purchaseTotals_currency key to set the currency:
param_gwOptions_purchaseTotals_currency:"JPY"
The Gateway Options feature is not supported by all gateways that are integrated with Zuora. For information about parameters that can be supported by each gateway and the appropriate key to use in the key-value pairs, see the specific gateway integration article. Zuora sends all the information that you specify to the gateway. If you specify any unsupported gateway option parameters, they will be ignored without error prompts.
Credit Card Type Payment Pages
The following table lists the client parameter specifically supported for the Credit Card type of Payment Pages 2.0.
| Parameter | Required? | Description |
|---|---|---|
| param_supportedTypes | Optional |
This parameter overrides the credit card "Accepted Types" set up for your payment gateway. Supported values are:
Specify a comma-separated list of values with no space in between, e.g., "AmericanExpress, Visa, MasterCard". Payment Page will display the specified credit card type icons in the order given in the value. If you do not specify this parameter, the credit card "Accepted Types" displays the following credit card types by default:
|
| cityBlackList | Optional |
Use this parameter to block end users in blacklisted cities from creating credit card payment methods. If end users specify blacklisted cities in the City field when entering their credit card information, an error message is displayed and the payment method cannot be created. Note that you can also localize the blacklist cities and error messages. |
| cityWhiteList | Optional |
Use this parameter to always allow end users in whitelisted cities to create credit card payment methods. Note that you can also localize the whitelisted cities and error messages. |
| pmId | Optional |
Use this parameter to allow end customers to view and enter their existing credit card payment method information, such as the expiration date, CVC code and address information, and re-authenticate the credit card upon submission. Except for card number and cardholder name, all other credit card fields are available for editing in the Payment Pages 2.0 iFrame form. If an orphan payment method is associated with a billing account during re-authentication and if Payment Pages 2.0 iFrame is PCI compliant. The card information can not be fraudulently edited outside. This field maps to the |
| screeningAmount | Optional | For Chase Paymentech Orbital Gateway integrations, if the Safetech Fraud service is enabled, you can use the screeningAmount field to pass in the amount used for fraud screening for Credit Card validation transactions.
Two-decimal amount is supported. If |
Bank Transfer - Direct Debit Type Payment Pages
The following table lists the client parameters specifically supported for the Bank Transfer - Direct Debit type of Payment Pages 2.0.
| Parameter | Required? | Description |
|---|---|---|
| field_bankBranchCode | Optional | The branch code of the direct debit bank |
| field_bankCheckDigit | Optional | The check digit in the international bank account number, which confirms the validity of the account |
| field_bankCity | Optional | The city of the direct debit bank |
| field_bankPostalCode | Optional | The zip code or postal code of the direct debit bank |
| field_bankStreetName | Optional | The name of the street of the direct debit bank |
| field_bankStreetNumber | Optional | The number of the direct debit bank |
| field_businessIdentificationCode | Optional | The business identification code for direct payment methods |
| field_IBAN | Optional | The International Bank Account Number |
Parameters for implementing payment flows
In the Z.render function, you can pass in additional parameters to support processing one-time payments or recurring payments in payment flows. For details about these parameters, see Implement Payment Pages 2.0 to support one-time payment flows.