knowledgecenter.zuora.com Open in urlscan Pro
2600:9000:2057:8000:1b:7e59:edc0:93a1 Public Scan

Back to summary

Submitted URL:
https://knowledgecenter.zuora.com/Zuora_Collect/Hosted_Payment_Pages/F_Client_Parameters_for_Payment_Pages_2.0#Credit_Card_Type_Pa...
Effective URL:
https://knowledgecenter.zuora.com/Zuora_Payments/Hosted_Payment_Pages/F_Client_Parameters_for_Payment_Pages_2.0
Submission: On September 14 via api (September 14th 2023, 10:48:19 am UTC) from US — Scanned from DE

Form analysis
3 forms found in the DOM

https://knowledgecenter.zuora.com/Zuora_Payments/Hosted_Payment_Pages/F_Client_Parameters_for_Payment_Pages_2.0#Credit_Card_Type_Payment_Pages

<form id="searchForm" class="su__search-forms su__w-100 su__px-3 su__px-sm-1 su__m-0 ng-pristine ng-valid" ng-submit="clickSearch(true, true)"
  action="https://knowledgecenter.zuora.com/Zuora_Payments/Hosted_Payment_Pages/F_Client_Parameters_for_Payment_Pages_2.0#Credit_Card_Type_Payment_Pages">
  <div class="su__d-flex su__form_height">
    <div class="su__search_form su__flex_box su__position-relative">
      <div class="su__w-100 su__bg-white-50 su__radius-2 su__position-relative su__autocomplete" ng-mouseleave="closeAutoComplete()">
        <input id="md-auto" class="su__form-control su__autocomplete-input su__md-autocomplete-rtl ng-pristine ng-untouched ng-valid ng-empty" type="text" placeholder="Search here" ng-model="searchString" ng-change="search(searchString)"
          ng-focus="search(searchString)" ng-keyup="($event.key == 'ArrowUp' || $event.key == 'ArrowDown' || $event.key == 'Enter') &amp;&amp; upOrDownKeyPress($event)" ng-model-options="{ debounce: 500 }" aria-invalid="false" style="">
        <!-- ngIf: searchString.length -->
        <!-- ngIf: showAutocompleteLoader -->
        <!-- ngIf: items.length !== 0 && showAutocomplete -->
      </div>
      <div class="input-group-button">
        <div class="advance-button-group" role="group">
          <button type="button" ng-click="clickSearch(true, true)" class="mt-inputredirect-button button button-success su__search-button">
          </button>
        </div>
      </div>
      <!-- </md-autocomplete> -->
      <!-- <div class="su__search_btn su__position-absolute su__zindex">
                        <div class="su__search-button su__btn su__bg-transparent" ng-click="clickSearch(false, true)">
                            <svg class="su__search-icons" version="1.1" id="Capa_1" x="0px" y="0px" viewBox="0 0 330 330" style="enable-background:new 0 0 330 330;" xml:space="preserve" xmlns="http://www.w3.org/2000/svg">
                                <path d="M325.606,304.394L223.328,202.117c16.707-21.256,26.683-48.041,26.683-77.111C250.011,56.077,193.934,0,125.005,0
                                C56.077,0,0,56.077,0,125.006C0,193.933,56.077,250.01,125.005,250.01c29.07,0,55.855-9.975,77.11-26.681l102.278,102.277
                                C307.322,328.536,311.161,330,315,330s7.678-1.464,10.606-4.394C331.465,319.749,331.465,310.251,325.606,304.394z M30,125.006
                                C30,72.619,72.619,30,125.005,30c52.387,0,95.006,42.619,95.006,95.005c0,52.386-42.619,95.004-95.006,95.004
                                C72.619,220.01,30,177.391,30,125.006z" ></path>
                                <g>
                                </g>
                            </svg>
                        </div>
                    </div> -->
    </div>
  </div>
</form>

/Special:Search

<form action="/Special:Search">
  <input name="qid" id="mt-qid-skin" type="hidden" value="">
  <input name="fpid" id="mt-search-filter-id" type="hidden" value="230">
  <input name="fpth" id="mt-search-filter-path" type="hidden">
  <input name="path" id="mt-search-path" type="hidden" value="">
  <label class="mt-label" for="mt-site-search-input"> Search </label>
  <input class="mt-text mt-search search-field" name="q" id="mt-site-search-input" placeholder="How can we help you?" type="search">
  <button class="mt-button ui-button-icon mt-icon-site-search-button search-button" type="submit"> Search </button>
</form>

POST https://knowledgecenter.zuora.com/Special:UserLogin?returntotitle=Zuora_Payments%2FHosted_Payment_Pages%2FF_Client_Parameters_for_Payment_Pages_2.0

<form action="https://knowledgecenter.zuora.com/Special:UserLogin?returntotitle=Zuora_Payments%2FHosted_Payment_Pages%2FF_Client_Parameters_for_Payment_Pages_2.0" class="mt-form" method="POST" id="quick-login">
  <div class="mt-field">
    <input autocomplete="off" class="reset mt-text" id="username" name="username" placeholder="Username" type="text">
    <label class="title login-form-label mt-label" for="username">Username</label>
  </div>
  <div class="mt-field">
    <input autocomplete="off" class="mt-text" id="password" name="password" placeholder="Password" type="password">
    <label class="title login-form-label mt-label" for="password">Password</label>
  </div>
  <div class="mt-field mt-submit">
    <button class="ui-button ui-button-primary" type="submit">Sign in</button>
  </div>
</form>

Text Content

Skip to main content
LOGIN
EMPLOYEE LOGINCUSTOMER LOGIN

CLIENT PARAMETERS FOR PAYMENT PAGES 2.0

1. Search site
Search Search
Go back to previous article
2. 1. Username
Password
Sign in
2. Sign in
* Sign in
* Forgot password

Expand/collapse global hierarchy
1. Home
2. Zuora Payments
3. Hosted Payment Pages
4. Client Parameters for Payment Pages 2.0

Expand/collapse global location

* 日本語のコンテンツは機械翻訳されており、補助的な参照を目的としています。機械翻訳の精度は保証できません。英語版が正となります。また、現時点では検索機能は日本語での検索をサポートしていません。翻訳に関するフィードバックについては、docs@zuora.comに送信してください。

CLIENT PARAMETERS FOR PAYMENT PAGES 2.0

1. Last updated Sep 11, 2023
2. Save as PDF
3.

Table of contents
1. General Parameters
2. Gateway Options
3. Credit Card Type Payment Pages
4. Bank Transfer - Direct Debit Type Payment Pages
5. Parameters for implementing payment flows

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 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 (doPayment is true).

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.

documents Optional

Only available for one-time payment flows.

An array of invoices to be paid in this transaction, containing the following
fields:

* type - The value must be invoice.
* ref - The value must be the invoice number, such as INV0000001.

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. An orphan
payment method must be associated with an account within 10 days. Otherwise, it
will be deleted.

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

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 field_gatewayName field.

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 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 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. The following gateways support Gateway Options:

* Adyen
* Adyen Integration v2.0
* Authorize.net
* BlueSnap
* Braintree
* Chase Orbital Payment
* Chase Orbital Version 7.0.1 Integration
* CyberSource
* CyberSource Token
* Merchant e-Solutions
* Moneris
* Orbital (Chase Paymentech)
* PayPal Adaptive Payments
* PPRO (previously known as Allpago)
* QuickGateway
* Stripe
* Vantiv
* Vantiv (Now Worldpay)
* Verifi
* Worldline Global Collect (previous Ingenico ePayments)

For information about extra 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:

* Visa
* MasterCard
* AmericanExpress
* Discover
* Dankort

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:

* Visa
* Mastercard
* Discover

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. Payment Pages
2.0 iFrame is PCI compliant. The card information can not be fraudulently edited
outside.

This field maps to the refId field in the response.

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 screeningAmount is not specified, the authorization amount is used for fraud
screening.

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.

1. Back to top
2. * Validate the Digital Signature for Payment Pages 2.0
* Payment Pages 2.0 Form Fields