Skip to main content

Customize Hosted Payment Method Pages


Customize Hosted Payment Method Pages

This article is for the Hosted Payment Method Pages (HPM) 1.0. Zuora has deprecated HPM1.0. There are no further plans for HPM 1.0 and Zuora will no longer provide support for any issues with HPM 1.0. Payment Pages 2.0 are now generally available, and are a replacement for HPM 1.0. To migrate from HPM 1.0 to Payment Pages 2.0, see this migration guide.


After setting up the Hosted Payment Method pages for your site, you can use additional features to customize how you use Hosted Payment Method pages. 

Pre-Populate Data into the iFrame

You can pre-populate the input or hidden fields on a hosted page with the values that are passed in as parameters. To pre-populate a field, append the parameter to the URL in the format field_[Field Name].

For example, to select Visa by default: field_creditCardType=Visa

You use this method to pre-populate any field with values. A full list of the of the input fields can be found in Hosted Payment Method pages fields.

Pre-Populating Credit Card Information

When you pre-populate Hosted Payment Method pages with credit card information, specifically the credit card number, CVV number, expiration year, and expiration month, you must encrypt those fields values using the Zuora API Security key. The resulting values are encoded using Base64 and URL encoders. If the values are not encrypted, these credit card fields will not be pre-populated on the Hosted Payment Method pages.

Using the following steps, implement the Hosted Payment Method iFrame to ensure the sensitive payment information is being handled securely.

  1. AES encryption uses a 32 byte key to encrypt the data, and you use the API Security Key to encrypt the Hosted Payment Method field values. Since the tenant API Security Key has more than 32 bytes, you need to truncate the API Security Key to only include the first 32 bytes. The code below shows how to truncate the key.

* Builds the secret key by truncating or padding the encryption in case it is more or less than 32 bytes.
* @return
* @throws UnsupportedEncodingException
private SecretKeySpec getKeySpec() throws UnsupportedEncodingException
     byte[] newbytes =Arrays.copyOf(encryptionKey.getBytes("UTF-8"), 32);     
     SecretKeySpec keySpec =  new SecretKeySpec(newbytes, "AES");
     return keySpec;
  1. Use the truncated key to perform the AES encryption on the credit card fields. The encrypted string is expected to be Base64 and URL encoded so that it can be used to build the iFrame URL.

* Encrypts the plain text using the key and AES algorithm
* @param plainText
* @param keySpec - generated in Step1.
* @return
public  String encrypt(String plainText, SecretKeySpec keySpec)
     try {
          // Instantiate the cipher
          Cipher cipher = Cipher.getInstance("AES");
          cipher.init(Cipher.ENCRYPT_MODE, keySpec);

          byte[] encryptedTextBytes = cipher.doFinal(plainText.getBytes("UTF-8"));
          String encryptedText = new String(org.apache.commons.codec.binary.Base64.encodeBase64(encryptedTextBytes));

          return encryptedText;
     }catch(Exception ex) {  
     return null;

Pass Information to the Callback Page

You can pre-load a hosted page with up to five passthrough parameters. The parameters will be appended in the callback. This is useful for merchants who would like to have specific pieces of information returned to the callback path, e.g. internal confirmation numbers, version test codes, etc. The passthrough  parameters are:

  • field_passthrough1
  • field_passthrough2
  • field_passthrough3
  • field_passthrough4
  • field_passthrough5

The passed in fields are sent back to the callback URL using the same name.

For example, for a request like the following:​&field_passthrough1=Capture&field_passthrough2=Step2

The callback would look like the following:

Set Input Fields in Hosted Payment Method Pages

You can set input fields entered from your website and set them in the embedded Hosted Payment Method page iFrame. For example, you can set the Bill-to information based on the Ship-to information a subscriber has entered on your website.

The JavaScript ZXD.postMessage function is used to copy input fields from your website into the Hosted Payment Method page iFrame​ fields. This integration must be added to the parent page on your website where the Hosted Payment Method page iFrame​ is embedded.

Most Hosted Payment Method page iFrame​ fields are supported, except for the following financially-sensitive fields:

  • Credit card number
  • Credit card security code
  • Credit card type
  • Bank account number
  • Bank Account Name

For a full list of supported fields, see Hosted Payment Method Page Fields.

Do not use the field__ prefix on field names when you pass the field names to postMessage to set input fields.

ZXD.postMessage Function Signature

The postMessage function has the following input parameters:




The format of the message, setField(FieldName:FieldValue)


The target URL

target The target contentWindow

The postMessage function can be downloaded from or

Sample Code

The following sample code illustrates how to set the Hosted Payment Method iFrame field, creditCardAddress1, with the input value entered from your website.

function copyField(hosted_iframe_id) {
    var src = document.getElementById(hosted_iframe_id).src + '#' + encodeURIComponent(document.location.href);
    document.getElementById(hosted_iframe_id).src = src;

    ZXD.postMessage("setField(creditCardAddress1:123 Lincoln Avenue)", src, document.getElementById(hosted_iframe_id).contentWindow);

Override Accepted Credit Card Type List

The credit cards logos shown on Hosted Payment Method pages are configured when you set up your payment gateway in the Zuora application. However, the merchant has the ability to dynamically overwrite the credit card "Accepted Types" configuration by passing in a comma-separated value into the hosted page. If a value has been passed in, the configuration will be ignored. If a value has not been passed in, the configured values will be shown on the iFrame.

For example, if your gateway is configured to accept Visa, MasterCard, and Amex but you want to only show Visa and MasterCard on your iFrame, you would pass in the following to the iFrame URL:


Send Gateway Options

Gateway Options is a feature that allows merchants to pass additional parameters to the payment gateway that currently are not supported by the Hosted Payment Method pages. This is particularly useful for merchants who want to do customized reporting with payment gateways that support the Gateway Options feature, such as CyberSource and Verifi.  

The merchant has the option to submit information to the payment gateway associated with the hosted page. The hosted page can take key/value pairs to be sent as part of the gateway options when the payment method is created. Use the format param_gwOptions_[Key]=[Value] to append the key/value pairs.

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 append the following to the Hosted Payment Method pages URL to change the authorization request from the default currency, AUD, to JPY. CyberSource uses the purchaseTotals_currency key to set the currency.


The URL with the above Gateway Option would be:

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 Hosted Payment Method pages with Ingenico ePayments. For this gateway, Zuora sends the Tenant-level default currency.

The following gateways support Gateway Options:

  • Adyen
  • Adyen Integration 2.0
  • BlueSnap
  • CyberSource, Payment API v2.0 
  • CyberSource Tokenization
  • First Data UCom
  • GoCardless
  • Merchant e-Solutions
  • Moneris
  • Chase Orbital
  • PayPal Adaptive Payments
  • QuickGateway
  • Verifi