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.

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_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: https://www.domain.com.
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

encrypted_fields

-

Set to the following:

"#field_creditCardNumber​#field_cardSecurityCode
​#field_creditCardExpirationMonth
​#field_
creditCardExpirationYear"

encrypted_values - See Obtain the Encrypted Credit Card Information for Direct POST 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  

Obtain the Encrypted Credit Card Information for Direct POST

To obtain the encrypted credit card information for the encrypted_values field, complete the following steps:

  1. Construct the credit card information to a string in the following format:
    #field_CreditCardNumber#field_CreditCardSecurityCode#field_CreditCardExpirationMonth#field_CreditCardExpirationYear
  2. Use Base64 encoding to encode the formatted string.
  3. Encrypt the encoded result from Step 2 with the public key.
  4. Use Base64 encoding to encode the encrypted result from Step 3.

Credit card information can be encrypted either on your payment web page directly, or on your own backend before the encrypted value is sent to the Zuora system. Sample codes are provided below for both cases.

Sample Codes of Encryption

Option 1: The following sample code uses the encryptText Java function and HPM2Security.js to encrypt credit card information directly on the web page.

The HPM2Security.js can be loaded on your web page from the following websites:

Some open source libraries are referenced by HPM2Security.js. Zuora does not maintain these open source libraries thus cannot guarantee they work correctly with your system.

function buildEncryptedValues(...) {
  // 1) Construct credit card data to a string in the desired format
  var unencrypted_values = "#" + creditCardNumber + "#" +
                          cardSecurityCode + "#" + creditCardExpirationMonth + "#" +
                          creditCardExpirationYear;

  // 2) Base64 encode the string, 3) Encrypt the Base64 string 
  // and 4) Base64 encode the encrypted data
  return encryptText(unencrypted_values, publicKey);
}

/**
 * encrypt the text using the specified public key.
 * @param text the text to be encrypted.
 * @param key the public key.
 * @returns Base64 encoded encrypted data.
 */
function encryptText(text, key) {
  if (key) {
    try {
      var key = pidCryptUtil.decodeBase64(key);
      var rsa = new pidCrypt.RSA();
      //ASN1 parsing
      var asn = pidCrypt.ASN1.decode(pidCryptUtil.toByteArray(key));
      var tree = asn.toHexTree();
      
      //setting the public key for encryption with retrieved ASN.1 tree
      rsa.setPublicKeyFromASN(tree);
      
      // Base64 encode and encrypt the string
      var crypted = rsa.encrypt(text);

      return pidCryptUtil.encodeBase64(pidCryptUtil.convertFromHex(crypted));
    } catch(e) {
      console.info(e);
    }
  }
  // return origin text if unable to encrypt
  return text;
}

Option 2: The following sample code uses the RsaEncrypter.encrypt Java function to encrypt credit card information on a Java backend. The code below depends on several libraries. You can find those libraries in Payment Pages 2.0 sample code repository.

import com.zuora.rsa.security.encrypt.RsaEncrypter;
import org.apache.commons.codec.binary.Base64;

public class HPMUtils {
    public static String buildEncryptedValues(...) {
        // 1) Construct the credit card data to a string in the desired format
        String unencrypted_values = "#" + creditCardNumber + "#" +
                cardSecurityCode + "#" + creditCardExpirationMonth + "#" +
                creditCardExpirationYear;

        // 2) Base64 encode the string
        String base64Data = new String(Base64.encodeBase64(unencrypted_values.getBytes()));
        // 3) Encrypt the Base64 data and 4) Base64 encode the encrypted data
        return RsaEncrypter.encrypt(base64Data, publicKey);
    }
}

Direct POST Fields for Bank Transfer - ACH

Field Name

Maximum Length Comments

field_achBankABACode

9  
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

Tags

Classifications

(not set)