Direct POST Form Fields for Payment Pages 2.0

Knowledge Center > Billing and Payments > Hosted Payment Pages > Payment Pages 2.0 > Implement Payment Pages 2.0 via Direct POST > Direct POST Form Fields for Payment Pages 2.0

Direct POST Form Fields for Payment Pages 2.0

When constructing a Payment Page form via HTML Direct POST, use the fields in this article to customize your Payment Page. You specify the fields as an HTML <input> elements, where the name attribute is set to the field name shown in the below tables. For example: 

<input type="text" name="field_creditCardHolderName" value="<[cardholder name]>"/>

See Implement Direct Post for Payment Pages 2.0 for more information on how to create an HTML form for a Payment Page.

Direct POST Fields for All Payment Types

Field Name Required? Description
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_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.

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.

If both "currency" and "param_gwOptions_purchaseTotals_currency" are given, the "param_gwOptions_purchaseTotals_currency" parameter takes precedence over "currency."

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

The IP address of the user when the payment method was created or updated. Some gateways use this field for fraud prevention. 

Only IPv4 addresses are supported.

field_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 about retrieving the public key through the REST API.

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

Optional Specifies the number of allowable consecutive failures Zuora attempts with the payment method before stopping.







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

field_style Required

Set to "iframe".

field_useDefaultRetryRule Optional Determines whether to use the default retry rules configured in the Payments settings.
host Required The domain address from which your Payment Page will be served. This is also the domain where your callback page resides. The value should be in the format:
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.
method Required Set to "submitPage"
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 Payments Settings. Overrides the default gateway you set up during the Payment Page configuration. 
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.
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.

Direct POST Fields for Credit Card

Field Name Maximum Length Comments



Set to:


encrypted_values - See below.
field_creditCardAddress1 255


field_creditCardAddress2 255  
field_creditCardCity 40  
field_creditCardCountry 3

Set it to a 3-digit ISO code

field_creditCardHolderName 50


field_creditCardPostalCode 20  
field_creditCardState 50

State or province

field_creditCardType -

Set to one of the following:

  • "Visa"
  • "MasterCard"
  • "AmericanExpress"
  • "Discover"
field_email 80  
field_phone 40  

Encrypt Direct POST Credit Card Fields

In the credit card type Payment Pages, construct the string for the encrypted_values field using the following information:

  • Credit card number (field_CreditCardNumber)
  • Credit card security code (field_CreditCardSecurityCode)
  • Credit card expiration month (field_CreditCardExpirationMonth)
  • Credit card expiration year (field_CreditCardExpirationYear)

Follow the below steps to construct the credit card fields for HTML Direct POST:

  1. Construct the string in the following format:
  2. Encode the formatted string to Base64.
  3. Encrypt the encoded string with the public key.
    You can use the RsaEncrypter.encrypt java function defined in the Zuora security library to encrypt the string. 
  4. Encode the encrypted string to Base64.
  5. Set the encoded string to the encrypted_values field.

The following is a sample code to encrypt credit card information. The code below depends on several libraries. You can find those libraries in Payment Pages 2.0 sample code repository.

import org.apache.commons.codec.binary.Base64;

public class HPMHelper {

   public static void prepareParamsAndFields(...)
         String unencrypted_values = "#" + creditCardNumber + "#" + 
         cardSecurityCode + "#" + creditCardExpirationMonth + "#" + 
         String encrypted_values = RsaEncrypter.encrypt(
            new String(Base64.encodeBase64(unencrypted_values.getBytes())), 

The below JavaScript code segment shows how to invoke the above Java encryption function. 

<%@ page language="java" contentType="text/html; charset=UTF-8" 
<%@ page import="com.zuora.hosted.lite.util.HPMHelper" %>
<%@ page import="java.util.Map" %>
<%@ page import="java.util.HashMap" %>
<%@ page import="java.util.Properties" %>
<%@ page import="" %>
   Map<String, String> params = new HashMap<String, String>();
   params.put("style", "inline");
   params.put("submitEnabled", "true");
   params.put("locale", request.getParameter("locale"));
   Properties prepopulateFields = new Properties();
      new FileInputStream(request.getServletContext().getRealPath("WEB-INF") + 

      params, (Map)prepopulateFields);

See JavaScript sample code for the complete code sample.

Direct POST Fields for Bank Transfer - ACH

Field Name

Maximum Length Comments


field_achBankAccountName 150  
field_achBankAccountNumber 40  
field_achBankAccountType 50

Set to one of the following:

  • "Checking"
  • "Saving"
  • "BusinessChecking "
field_achBankName 150  

Direct POST Fields for Bank Transfer - Direct Debit (UK) 

Field Name Maximum Length Comments
field_agreement_checkbox - This field is required. Set it to "On".
field_bankAccountName 30  
field_bankAccountNumber 30  
field_bankBranchCode 5  
field_bankCheckDigit  2  
field_bankCity 2  
 field_bankCode 9  
 field_bankName 40  
field_bankPostalCode 10  
field_bankStreetName 35


field_bankStreetNumber 10  
field_bankTransferType - Set to "DirectDebitUK"
field_businessIdentificationCode 11  
field_city  40  
field_existingMandateStatus -

Set to one of the following:

  • "Yes"
  • "No"
field_firstName 15 Account holder's first name
field_IBAN 21

International Bank Account Number

field_lastName  35 Account holder's last name
field_mandateCreationDateDay 2 Number for day of the week
field_mandateCreationDateMonth 2 Number for the month
field_mandateCreationDateYear 4 Year number
field_mandateId  18

Account number

field_mandateReceivedStatus -

Set to one of the following:

  • "Yes"
  • "No"
field_mandateUpdateDateDay 2 Number for day of the week
field_mandateUpdateDateMonth 2 Day number of the month
field_mandateUpdateDateYear 4 Year number
field_postalCode 10  
field_state 35  
field_streetName  50  
field_streetNumber 15  

Direct POST Fields for Bank Transfer - SEPA

Field Name Maximum Length Comments
field_bankAccountName 30  
field_bankAccountNumber 30

This is the IBAN.

field_bankCity 35  
field_bankCode 9  
field_bankName 40  
field_bankPostalCode 10  
field_bankStreetName 35  
field_bankStreetNumber 10  
field_bankTransferType - Set to  "SEPA".
field_businessIdentificationCode 11 Business ID code
field_city 40  
field_country 3

Set to a 3-digit ISO code.

field_existingMandateStatus -

Set to one of the following:

  • "Yes"
  • "No"
field_firstName 15


field_lastName 30  
field_postalCode 10  
field_state 35 State or province
field_streetName 50  
field_streetNumber 15  
field_mandateCreationDateDay 2 Number for day of week
field_mandateCreationDateMonth 2 Month number
field_mandateCreationDateYear 4 Year number
field_mandateId 18 Mandate ID
field_mandateReceivedStatus -

Set to one of the following:

  • "Yes"
  • "No"
field_mandateUpdateDateDay 2 Number for day of week
field_mandateUpdateDateMonth 2 Month number
field_mandateUpdateDateYear 4 Year number


Last modified



(not set)