PaymentMethod

From API Documentation

PaymentMethod contains information on how the contact pays for the account. In order to activate an account, you need to create a payment method.

Supported Calls

This object is used in the create, query, update, and delete calls.

Using PaymentMethod

For most of the Type field choices, if you choose one of the options, you cannot use the fields for any of the other choices.

If the payment type is ACH, then only populate the ACH fields; do not include credit card, direct debit, or PayPal information.
If the payment type is CreditCard, then only populate the credit card fields; do not include direct debit, PayPal or ACH information.
If the payment type is DirectDebit, then only populate the direct debit fields; do not include direct debit, PayPal or ACH information.
If the payment type is Paypal, then only populate the PayPal fields; do not include credit card, direct debit or ACH information.
The one exception is the DebitCard type. If the payment type is DebitCard, then all of the credit card fields are required.

The following table provides a summary:

If Using This PaymentMethod Type:	ACH	CreditCard	Paypal	DirectDebit
ACH	Yes	No	No	No
CreditCard	No	Yes	No	No
DebitCard	No	Yes	No	No
PayPal	No	No	Yes	No
DirectDebit	No	No	No	Yes

ACH, CreditCard, DebitCard, and PayPal are the only types supported for use with create calls.

Note: The ability to support the Direct Debit payment type is a Controlled Release feature. Contact Zuora Global Support for information about enabling this feature.

Fields

In addition to the following fields, zObject contributes additional fields. For information on the field types, see Field Types.

Name	Required?	Type	Allowed Operations: ● Yes ○ No	Allowable Values	Description
AccountId	No for the subscribe call; Yes otherwise	zns: ID	● Create ● Query ● Update ● Delete ● Filter	A valid account ID	The ID of the customer account with which this payment method is associated.
AchAbaCode	Yes when defining an ACH payment method; No otherwise	string	● Create ● Query ● Update ● Delete ● Filter	20 characters maximum	This is the nine-digit routing number or ABA number used by banks.
AchAccountName	Yes when defining an ACH payment method; No otherwise	string	● Create ● Query ● Update ● Delete ● Filter	70 characters maximum	This is the name of the account holder (a person or a company).
AchAccountNumber	Yes when defining an ACH payment method. Otherwise, not required.	string	● Create ○ Query ○ Update ● Delete ○ Filter	50 characters maximum, numbers and hyphens only.	This is the bank account number to be used with the ACH payment.
AchAccountNumberMask	Read only field generated by Zuora when creating an ACG payment method.	string	○ Create ● Query ○ Update ○ Delete ● Filter	32 characters maximum	This is a mask to help hide the account number. For example: XXXXXXXXX54321
AchAccountType	Yes when defining an ACH payment method. Otherwise, not required.	string	● Create ● Query ● Update ● Delete ● Filter	BusinessChecking, Checking, Saving	This is the type of bank account the ACH payment is coming from.
AchBankName	Yes when defining an ACH payment method; No otherwise	string	● Create ● Query ● Update ● Delete ● Filter	70 characters maximum	This is the name of the bank where the ACH payment account is held.
Active	No	boolean	○ Create ● Query ○ Update ○ Delete ● Filter	True or False	Specifies which payment methods are allowed within Zuora. The default value is `false`. Note: Active signifies the payment method types that are accepted, which you can specify within Z-Billing settings. This field does not apply to to electronic payment methods, such as credit cards where you entered the credit card number or a PayPal account.
BankBranchCode	No	string	○ Create ● Query ○ Update ○ Delete ● Filter
BankCheckDigit	No	string	○ Create ● Query ○ Update ○ Delete ● Filter
BankCity	No, intended for DirectDebit payment methods only	string	○ Create ● Query ○ Update ○ Delete ● Filter		This is the city for the address of the bank used for Direct Debit.
BankCode	Yes for DirectDebit, no otherwise	string	○ Create ● Query ○ Update ○ Delete ● Filter		This is the code/number that identifies the bank. Also known as "sort code."
BankIdentificationNumber	No, read-only field	string	○ Create ● Query ○ Update ○ Delete ● Filter	6 characters maximum	This is the first six digits of the PaymentMethod, such as the credit card number or account number. This is often used by banks to identify a payment method rather than its mask (trailing 4 digits of a credit card).
BankName	No, intended for DirectDebit payment methods only	string	○ Create ● Query ○ Update ○ Delete ● Filter		This is the name of the bank used for Direct Debit.
BankPostalCode	No, intended for DirectDebit payment methods only	string	○ Create ● Query ○ Update ○ Delete ● Filter		This is postal code of the bank used for Direct Debit.
BankStreetName	No, intended for DirectDebit payment methods only	string	○ Create ● Query ○ Update ○ Delete ● Filter		This is the name of the street for the address of the bank used for Direct Debit.
BankStreetNumber	No, intended for DirectDebit payment methods only	string	○ Create ● Query ○ Update ○ Delete ● Filter		This is the number for the street address of the bank used for Direct Debit.
BankTransferAccountName	No, intended for DirectDebit payment methods only	string	○ Create ● Query ○ Update ○ Delete ● Filter		This is the name on the bank account used for direct debit.
BankTransferAccountNumber	Yes for DirectDebit, no otherwise	string	○ Create ● Query ○ Update ○ Delete ● Filter		This is the account number for of the customer's bank account.
BankTransferAccountType	No	string	○ Create ● Query ○ Update ○ Delete ● Filter
BankTransferType	Yes for DirectDebit, no otherwise	string	○ Create ● Query ○ Update ○ Delete ● Filter	AutomatischIncasso (NL), LastschriftDE (Germany), LastschriftAT (Austria), DemandeDePrelevement (FR), DirectDebitUK (UK Direct Debit), Domicil (Belgium),LastschriftCH (CH), RID (Italy), OrdenDeDomiciliacion (Spain)	This is specifies the type of DirectDebit that is being used. Value is dependent on the country of the user.
CreatedById	System generated, always exists	zns:ID	○ Create ● Query ○ Update ○ Delete ● Filter	This field is not editable. 32 characters maximum.	Available as of version 20.0 of the API. The Zuora system automatically generates this Id of the user who created the object.
CreatedDate	Yes, system generated	dateTime	○ Create ● Query ○ Update ○ Delete ● Filter	This field is not editable.	The Zuora system automatically generates this date when the payment method is created.
CreditCardAddress1	No	string	● Create ● Query ● Update ● Delete ● Filter	255 characters maximum	The first line of the billing address for the credit or debit card holder. This is used only when creating credit or debit card payment methods.
CreditCardAddress2	No	string	● Create ● Query ● Update ● Delete ● Filter	255 characters maximum	The second line of the billing address for the credit or debit card holder. This is used only when creating credit or debit card payment methods.
CreditCardCity	No	string	● Create ● Query ● Update ● Delete ● Filter	40 characters maximum	The billing address's city. This is used only when creating credit or debit card payment methods.
CreditCardCountry	No	string	● Create ● Query ● Update ● Delete ● Filter	40 characters	The country in which the billing address is located. Country names must be spelled in full. See the list of supported country names. This is used only when creating credit or debit card payment methods.
CreditCardExpirationMonth	Yes when defining a debit or credit card payment method; No otherwise	int	● Create ● Query ● Update ● Delete ● Filter	A two-digit number (01 through 12).	The expiration month of the credit or debit card.
CreditCardExpirationYear	Yes when defining a debit or credit card payment method; No otherwise	int	● Create ● Query ● Update ● Delete ● Filter	A four-digit number.	The expiration year of the credit or debit card.
CreditCardHolderName	Yes when defining a debit or credit card payment method; No otherwise	string	● Create ● Query ● Update ● Delete ● Filter	50 characters maximum	The full name (first or personal and last or family) of the holder of the credit or debit card.
CreditCardMaskNumber	This is a read only field generated by Zuora from the credit/debit card number.	string	○ Create ● Query ○ Update ○ Delete ● Filter	32 characters maximum, encrypted	A masked version of the credit or debit card number. This is a read-only field.
CreditCardNumber	Yes when defining a debit or credit card payment method; No otherwise	string	● Create ○ Query ○ Update ○ Delete ○ Filter	16 characters	The credit or debit card number. This is an insert-only field; it cannot be updated, and cannot be queried for security purposes.
CreditCardPostalCode	Optional. Only used when creating credit or debit card payment methods.	string	● Create ● Query ● Update ● Delete ● Filter	20 characters maximum	The billing address's postal code.
CreditCardSecurityCode	Not required.	string	● Create ○ Query ● Update ● Delete ● Filter	Credit card CVV or CVV2 security code.	This is the CVV or CVV2 security code. See Can I accept a CVV code for credit cards? for more information. Note: To ensure PCI compliance, this value is not stored and cannot be queried.
CreditCardState	Yes when defining a debit or credit card payment method; No otherwise	string	● Create ● Query ● Update ● Delete ● Filter	50 characters maximum	The billing address's state. Applies if the CreditCardCountry is either Canada or the US. State names must be spelled in full; we've provided a list of supported state names.
CreditCardType	Yes when defining a debit or credit card payment method; No otherwise	string	● Create ● Query ● Update ● Delete ● Filter	AmericanExpress, Discover, MasterCard, or Visa. 32 characters maximum.	The type of credit or debit card that is being billed. The values are case sensitive and must be used exactly as shown here.
DeviceSessionId	No	string	● Create ● Query ● Update ● Delete ● Filter	255 characters maximum	This is 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).
Email	No	string	● Create ● Query ● Update ○ Delete ● Filter	80 characters maximum	The email address connected to the PaymentMethod. Please note that this field is in addition to the Bill-To Contact email address.
IPAddress	No	string	● Create ● Query ● Update ● Delete ● Filter	15 characters maximum	This is 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, and Verifi supports this field).
LastFailedSaleTransactionDate	No, read-only	datetime	○ Create ● Query ○ Update ○ Delete ● Filter	This is a read-only field	The is the date of the last failed attempt at collecting payment with this payment method.
LastTransactionDateTime	No, read-only, system generated	dateTime	● Create ● Query ● Update ● Delete ● Filter	A valid dateTime value	The date of the most recent transaction.
LastTransactionStatus	No	string	● Create ● Query ● Update ● Delete ● Filter	This is a read-only field	The status of the most recent transaction. See LastTransactionStatus Values for a list of values.
MaxConsecutivePaymentFailures	No	short	● Create ● Query ● Update ● Delete ● Filter		Specifies the number of allowable consecutive failures Zuora will make with the payment method before stopping.
Name	No. Read-only field.	string	○ Create ● Query ○ Update ○ Delete ● Filter	50 characters maximum	Only applies to "Active" default payment methods that you specify as valid payment methods in Z-Billing settings. You cannot specify names for new payment methods.
NumConsecutiveFailures	No. Read-only field.	int	○ Create ● Query ● Update ○ Delete ● Filter		Number of consecutive failed payment for this payment method. It is reset to 0 upon successful payment. As of version 28.0 you can use the API to update (reset) this to 0.
PaymentMethodStatus	No	string	○ Create ● Query ○ Update ○ Delete ● Filter	Active, Closed	Specify the status of the payment method, either Active or Closed.
PaymentRetryWindow	No	short	● Create ● Query ● Update ● Delete ● Filter	The minimum value is 1. The maximum value is 6000.	Use the retry interval setting to prevent a payment attempt if the last failed payment was within the last '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. Please note that if you want to retry 'once a day', we recommend that you enter 22 or 23 hours as 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`.
PaypalBaid	Yes when defining a PayPal payment method; No otherwise	string	● Create ● Query ○ Update ○ Delete ● Filter	64 characters maximum	The PayPal billing agreement ID. This is a "contract" established between two PayPal accounts. Typically, the selling party initiates a request to create a BAID and sends it to buying party for acceptance. After that, the seller can keep track of the BAID and use it for future charges against the buyer.
PaypalEmail	Yes when defining a PayPal payment method; No otherwise	string	● Create ● Query ○ Update ○ Delete ● Filter	80 characters maximum	The email address associated with the account holder's PayPal account (or of the PayPal account of the person paying for the service).
PaypalPreapprovalKey	Yes if using PayPal Adaptive Payments gateway, no otherwise	string	● Create ● Query ○ Update ○ Delete ● Filter	A valid PayPal Adaptive Payments preapproval key. 32 characters maximum.	This is a key that is obtained from PayPal's Adaptive Payments API. Note that Zuora does not create this, nor does it call PayPal to generate it. You must use PayPal's Adaptive Payments' API to generate this key, and then pass to Zuora. Zuora will use this key to authorize future payments to PayPal's Adaptive Payments API.
PaypalType	Yes if using PayPal Adaptive Payments or Payflow Pro (Express Checkout) gateways. Otherwise, not required.	string	● Create ● Query ○ Update ○ Delete ● Filter	ExpressCheckout or AdaptivePayments	Specifies which PayPal gateway, either PayFlow Pro (Express Checkout) or Adaptive Payments.
Phone	No	string	● Create ● Query ● Update ● Delete ● Filter	40 characters maximum	The phone number that the account holder registered with the bank. This field is used for credit card validation when passing to a gateway.
SkipValidation	No	boolean	● Create ○ Query ○ Update ● Delete ○ Filter	True, False	Used for subscribe(), create() and update(). Specifies that the payment method should be created even if authorization fails with the payment gateway.
TotalNumberOfErrorPayments	Yes	integer	○ Create ● Query ○ Update ○ Delete ● Filter		The number of error payments that have occurred using this payment method.
TotalNumberOfProcessedPayments	Yes	integer	○ Create ● Query ○ Update ○ Delete ● Filter		The number of successful payments that have occurred using this payment method.
Type	Yes	string	● Create ● Query ○ Update ○ Delete ● Filter	ACH, Cash, Check, CreditCard, CreditCardReferenceTransaction, DebitCard, Other, PayPal, WireTransfer	The type of payment method being used. The values are case sensitive and must be used exactly as shown here. See Using PaymentMethod for more information.
UpdatedById	System generated, always exists	ZNS:Id	○ Create ● Query ○ Update ○ Delete ● Filter	This field is not editable. 32 characters maximum.	Available as of version 20.0 of the API. The Zuora system automatically generates this Id of the user who last updated the object.
UpdatedDate	Yes, system generated, always exists	dateTime	○ Create ● Query ○ Update ○ Delete ● Filter	This field is not editable.	The Zuora system automatically generates this date when the payment method is modified.
UseDefaultRetryRule	Yes	boolean	● Create ● Query ● Update ● Delete ● Filter	true, false	Set this to `true` to use the default retry rules configured in the Z-Payments Administration settings. Set this to `false` to set the specific rules for this payment method. In this case, the fields PaymentRetryWindow and MaxConsecutivePaymentFailures are required.

LastTransactionStatus Values

The following are the possible values for the LastTransactionStatus field:

ABACodeIsInvalid	CardSecurityCodeCheckingFailed	ExceedsPerTransactionLimit	InvalidCreditCardNumber	ProcessorConnectionTimeOut
ACHTransactionNotAcceptedByMerchant	CardSecurityCodeCheckingFailedAuthorize	FieldFormatError	InvalidCreditExpirationDate	TheAccountNumberIsInvalid
AddressCheckingFailed	ClientConnectionTimeOut	FraudProtectionDeclined	InvalidCurrencyCode	TransactionMethodInvalid
AddressOrCardSecurityCodeCheckingFailed	CreditTransactionError	GatewaySecuritySettingFailed	InvalidMerchantInformation	TransactionTypeInvalid
Approved	Declined	GatewayServerBusy	InvalidTenderType	UserAuthenticationFailed
AuthorizationCodeInvalid	DuplicateTransaction	GeneralTransactionError	InvalidTransactionID	VersionParameterInvalid
AValidAmountIsRequired	ErrorTypeForACH	GenericErrorFromProcessor	IPBlockedByGateway	VoidTransactionError
BankAccountTypeInvalid	ExceedMaximumAmountSetting	HostConnectionTimeOut	NotSupportedTenderType

PaymentMethod

From API Documentation

Contents

Supported Calls

Using PaymentMethod

Fields

LastTransactionStatus Values

Views

Search

Important!

Getting Started

Z-Commerce API Fundamentals

Z-Commerce API Reference

Personal tools