Knowledge Center

Knowledge Center > Commerce > Hosted Commerce Pages > Payment Pages 2.0 > Client Parameters for Payment Pages 2.0

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.

Parameter Required? Description
authorizationAmount Optional

The initial authorization amount.

Specify a numeric value between 0 and 50,000, inclusive.

This value overrides the default authorization amount set for the specific payment gateway.

NoteNvy50.png This amount will always be automatically voided.

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.

Example: countryBlackList,
"USA,CAN,CHN"
 will result in United States, Canada, and China not appearing in the displayed list of countries.

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.

Example: countryWhiteList,
"USA,CAN,CHN"
 will result in only United States, Canada, and China appearing in the displayed list of countries.

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. A standalone payment method is deleted if it is not associated with a Zuora account within 240 hours.

field_deviceSessionId Optional The session ID of the user when the Payment Method was created or updated. Some gateways use this field for fraud prevention.
field_gatewayName Optional The name of the payment gateway
field_
maxConsecutivePaymentFailures
Optional Specifies the number of allowable consecutive failures Zuora attempts with the payment method before stopping.

field_passthrough1

field_passthrough2

field_passthrough3

field_passthrough4

field_passthrough5

Optional

Fields values to be sent back to the callback function or callback URL.

Use the fields when you want information not captured in your Payment Page form to be returned to the callback path, e.g., internal confirmation numbers, version test codes. etc.

 

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 rsa-signatures REST request. 

See Generate the Digital Signature for Payment Pages 2.0 about obtaining the public key through the REST API.

See Configure Payment Pages 2.0 about obtaining the public key in the Zuora UI.

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 Hoste 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. 
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:

  • inline: Your Payment Page form is embedded within your commerce page.
  • overlay: Your Payment Page form appears as an overlay when the form is loaded. 
submitEnabled Required

Flag to indicate that page submission is handled by Zuora or by the client site. The allowed values are:

  • true: Indicates that page submission will be handled by Zuora. This setting causes the the submit button rendered on the Payment Page form.
  • false: Indicates that page submission will be handled by client. This setting causes the submit button rendered outside of the Payment Page form.

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 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 integrated with Zuora. For example, Ingenico ePayments does not support Gateway Options, and customers cannot use multi currency on the Payment Pages with Ingenico ePayments. For this gateway, Zuora sends the Tenant-level default currency.

The following gateways support Gateway Options:

  • Adyen
  • Authorize.net
  • CyberSource
  • CyberSource Token
  • Merchant e-Solutions
  • Orbital (Chase Paymentech)
  • PayPal Adaptive Payments
  • QuickGateway
  • Vantiv
  • Verifi

See the articles for your payment gateway under Setting Up Payment Gateways to see the list of supported gateway options.

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

Overrides the credit card "Accepted Types" set up for your payment gateway. Supported values are: 

  • Visa
  • MasterCard
  • AmericanExpress
  • Discover

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.

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

 

Last modified
13:54, 26 Jul 2017

Tags

Classifications

(not set)