Skip to main content

Direct POST Form Fields for Payment Pages 2.0

Zuora

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. An orphan 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 number greater than 0.

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 for more information.

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

For a complete list of supported ISO country codes, see View countries or regions.

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.

Note that if you get NullValue when trying to obtain the encrypted credit card information for Direct POST, it is usually due to one of the following reasons:

  • The order of the credit card parameters is incorrect. 
  • The Javascript library HPM2Security.js is not used to encrypt.

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 the Payment Pages 2.0 sample code suite on Zuora GitHub site.

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  
field_achAddress1 255  
field_achAddress2 255  
field_achBankName 40  
field_achCity 40  
field_achCountry   A list of countries.
field_achPostalCode 20  
field_achState 50  

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.

For a complete list of supported ISO country codes, see View countries or regions.

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

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

Field Name Maximum Length Comments
field_bankAccountName 30  
field_bankAccountNumber 30

 

field_bankCode 9  
field_bankName 40  
field_bankCity 35  
field_bankPostalCode 10  
field_bankBranchCode 10  
field_bankStreetName 35  
field_firstName 15

 

field_lastName 35  
field_postalCode 10  
field_city 40  
field_state 35 State or province
field_email 255  
field_phone 40  
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_mandateReceived -

Set to one of the following:

  • "Yes"
  • "No"
field_existingMandateStatus -

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

Direct POST Fields for Stored Credentials

Zuora gives you the flexibility to perform cardholder initiated transactions (CITs) within or outside Zuora.

Perform CITs in Zuora

If you want to leverage Zuora to perform CITs, include the following fields in the Payment Page 2.0 form. Zuora will perform the credit card validation, and create a stored credential profile within the created payment method if it is valid. For more information about stored credential profiles, see Stored credential transactions.

Field Name Maximum Length Comments Required?
field_agreementSupportedBrands - A comma-separated list of stored credential transaction frameworks that the customer consent agreement applies to. For example, Visa,MasterCard Yes
field_mitConsentAgreementRef 128 Your reference for the stored credential consent agreement that you have established with the customer Yes
field_mitConsentAgreementSrc - Set this field to External Yes
field_mitCredentialProfileType - Set this field to Recurring Yes

Perform CITs outside Zuora

If you perform CITs outside Zuora, include the following fields in the Payment Page 2.0 form after the authentication and authorization are completed. Zuora will then skip the validation for the created credit card payment method. A typical scenario to include these fields in requests is the 3D Secure session.

Field Name Maximum Length Comments Required?
field_agreementSupportedBrands - A comma-separated list of stored credential transaction frameworks that the customer consent agreement applies to. For example, Visa,MasterCard Yes
field_mitConsentAgreementRef 128 Your reference for the stored credential consent agreement that you have established with the customer Yes
field_mitConsentAgreementSrc - Set this field to External. Yes
field_mitCredentialProfileType - Set this field to Recurring. Yes
field_mitProfileAction - Set this field to Persist. Yes
field_mitNetworkTransactionId 128 The networkTransactionId that you get from the payment gateway. Yes
field_mitGatewayToken1 128 The first token if the gateway provides. No
field_mitGatewayToken2 128 The second token if the gateway provides. No
field_mitGatewayToken3 128 The third token if the gateway provides. No