Skip to main content
Zuora Logo

Hosted Payment Method Page Fields

Zuora

Hosted Payment Method Page Fields

  1. Last updated
  2. Save as PDF

Overview

This page lists the fields that can be appended to the Hosted Payment Page URL to add functionality.

Field Prefixes

Add the following prefixes to the fields when you append the fields to the URL:

  • field_: Use the field_ prefix to pre-populate the values of these fields when the iframe is loaded. 
  • error_: Use the error_ prefix to indicate the fields having errors when the response is sent back from Zuora service. For example, error_cardSecurityCode can be a URL parameter passed back from Zuora indicating there is an error on the cardSecurityCode field.

For setting input fields with the values entered from your website, do not use the field_ or error_ prefix on field names. For example, if you want the subscriber's address to be copied to the Bill-to address in the Hosted Payment Method iFrame, the field referenced is creditCardAddress1 not field_creditCardAddress1.

Payment Method Fields

Field Name (case sensitive)

Description

Max Len

accountId

The Zuora system account ID of the contact with which this payment method is associated.

32

deviceSessionId

The (web) session ID of the user when the PaymentMethod was created or updated. This is used for fraud prevention with some gateways. If passed to Zuora, Zuora will pass this field to supported gateways. Currently, only Verifi supports this field.

255

ipAddress

The IP address of the user when the PaymentMethod was created or updated. This is used for fraud prevention with some gateways. If passed to Zuora, Zuora will pass this field to supported gateways. Currently, only PayPal, CyberSource, Authorize.Net, Verifi, Worldpay, and Allpago support this field.

15

useDefaultRetryRule

Set this to true to use the default payment run retry rules configured in the Payments Administration settings. Set this to false to set the specific rules for this payment method.

If you set this to false, you must specify values for the paymentRetryWindow and maxConsecutivePaymentFailures fields. 

5

paymentRetryWindow

Use the retry interval setting to prevent a payment attempt if the last failed payment was within the specified number of hours. For example, if the last failed payment was at 1PM and the retry interval is 4 hours, then a payment run at 2PM will not attempt a payment, but a payment run at 6PM will.

If you want to retry once a day, Zuora recommends that you enter 22 or 23 hours, because it is possible for a payment to be attempted at the end of the payment run on one day and the beginning of the payment run the next day.

This field is required if UseDefaultRetryRule is set to false.

6

maxConsecutivePaymentFailures

Specifies the number of allowable consecutive failures Zuora will make with the payment method before stopping.

6

Credit Card Type Fields

Field Name (case sensitive)

Possible Values

Max Len

creditCardType

supportedTypes

Visa, MasterCard, AmericanExpress, Discover

20

creditCardNumber1

string

16

creditCardExpirationMonth1

integer

2

creditCardExpirationYear1

integer

4

cardSecurityCode1

string

4

creditCardHolderName

string

50

creditCardCountry

3-digit ISO code

32

creditCardAddress1

string

255

creditCardAddress2

string

255

creditCardCity

string

40

creditCardState

string

50

creditCardPostalCode

string

20

phone

string

40

email

string

80

ACH Type Fields

Field Name (case sensitive)

Possible Values

Maximum Length

achBankABACode

string

9
achBankAccountNumber string 40
achBankAccountType Checking, Savings 50
achBankName string 150
achBankAccountName string 150
phone string 32
email string 255

Bank Transfer Fields

Field Name (case sensitive)  Possible Values  Max Len
 bankAccountNumber  String  30 
 bankAccountName  String   30 
 bankCode  String  9
 bankName  String  40 
 bankBranchCode  String  5 
 bankCheckDigit  String  2 
 bankStreetNumber  String 10 
 bankStreetName  String 35 
 bankCity  String 35 
 bankPostalCode  String 10 
 businessIdentificationCode  String  10 
 firstName  String 15 
 lastName  String 35 
 streetNumber  String 15 
 streetName  String 50 
 city  String 40 
 state  String 35 
 postalCode  String 10 
 IBAN  String 21 
 mandateReceivedStatus  Yes, No  1
 existingMandateStatus  Yes, No  1
 mandateId  String 18 
 mandateCreationDateDay  Integer  2
 mandateCreationDateMonth  Integer  2
 mandateCreationDateYear  Integer  4
 mandateUpdateDateDay  Integer  2
 mandateUpdateDateMonth  Integer  2
 mandateUpdateDateYear  Integer  4

Additional Fields

Field Name (case sensitive)

Possible Values

Description

retainValues

true, false

Use this to preload the new page with the page with the previously entered information that was saved in the browser cookie by appending the parameter &retainValues=true. You can preload the page with the previously entered information that was saved in the cookie.
bankTransferType DirectDebitUK

Use this only for the Direct Post request pattern for Bank Transfer HPM to set the bank transfer type.

1When pre-loading the Hosted Payment Method pages, these fields must be pre-populated with encrypted values. See Customizing Hosted Payment Method Pages for more information.