Skip to main content

PaymentMethod

Zuora

PaymentMethod

Payment methods are the ways in which customers pay for their subscriptions. Your customers can choose a payment method from your company's list of preferred payment methods.

The PaymentMethod object represents payment method details associated with a customer account. 

Electronic payment methods include credit cards, debit cards, bank transfers, and third-party processors, such as PayPal. Non-electronic methods, which must be made outside of Zuora Payments, are called external methods, and include checks, cash, and wire transfers.

You define payment methods in the web-based UI. The methods that you define are available for you to use for individual customer accounts in the API.

For more information on payment methods, see Key Concepts. For guidance on choosing which payment methods are right for your company, see Payment Method Acceptance

Supported Payment Methods

Payment Method Description

ACH

An Automated Clearing House (ACH) payment is a form of electronic funds transfer or bank transfer that provides a secure, efficient method of receiving payments through the ACH Network.

ACH is also called direct debit.

Bank Transfer

This payment method includes the following types:

  • SEPA. European Union payment integration for bank transfers in Euro denomination. 
  • Direct Debit UK (BACS)
  • AU Direct Entry (BECS)
  • Direct Debit DK (Betalingsservice)
  • Direct Debit SE (Autogiro)
  • Direct Debit CH (Lastschrift)
  • Direct Debit NZ (BECS)
  • AutomatischIncasso (NL)
  • Lastschrift DE (Germany)
  • Demande De Prelevement (FR)
  • Domicil (Belgium)
  • RID (Italy)
  • Orden De Domiciliacion (Spain)

Cash

Cash is money in the physical form of currency, such as bank notes or coins.

CC Reference Transaction

A credit card reference transaction reuses existing credit card information. If you need to recharge a credit card and you are not storing the credit card information in your local database, then you can perform a CC reference transaction. This method of payment is available if PayPal is used as the payment gateway.

Check

A check is a negotiable instrument instructing a financial institution to pay a specific amount of a specific currency from a specified demand account held in the depositor's name with that institution.

Credit Card

Purchasers can use credit cards to buy goods based on the card holder’s promise to pay for these goods and services. Zuora support Visa, Mastercard, American Express and Discover cards.

Debit Card

A debit card is also called a banking card, check card or ATM card. It is used as an alternative to cash when making purchases. The funds for a debit card purchase are withdrawn directly from the bank account. Zuora support Signature (or PIN-less) debit cards that have a Visa or Mastercard logo.

PayPal

With PayPal, customers can send payments securely online using a stored value account that is linked to a credit card, Signature (PINless) debit card, or bank account.

Wire Transfer

A wire transfer is a method of transferring money from one person or institution to another. A wire transfer can be made from one bank account to another bank account or through a transfer of cash at a cash office.

Other

Use this option for other payment methods.

The SOAP API does not support the following payment method types. Click the links to see more information about how to set up these payment methods.

Supported Calls

You can use this object with the following calls:

Field Descriptions

All field names are case sensitive. Check enumerated values in descriptions to confirm capitalization and spacing. See Field Types for additional information.

Name Required Create Allowed
Operations
Description

AccountId

required

Create
Query
Update
Delete
Filter

The ID of the customer account associated with this payment method. This field is not required for the subscribe() call, but is required for all other calls. including the create() call.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid account ID

Note: You can create a payment method without associating it with a customer account. To do it and change the AccountId field to optional, submit a request at Zuora Global Support.

If a payment method was created without an account ID associated, you can update the payment method to specify an account ID later in the update() call. However, if a payment method is already associated with a customer account, you cannot update the payment method to associate it with another account ID. You cannot remove the previous account ID and leave the AccountId filed empty in the update() call.

AchAbaCode

conditional

Create
Query
Update
Delete
Filter

The nine-digit routing number or ABA number used by banks. This field is only required if the Type field is set to ACH.

Type: string
Character limit: 9
Version notes: --
Values: a string of 9 characters or fewer

AchAccountName

conditional

Create
Query
Update
Delete
Filter

The name of the account holder, which can be either a person or a company. This field is only required if the Type field is set to ACH.

Type: string
Character limit: 70
Version notes: --
Values: a string of 70 characters or fewer

AchAccountNumber

conditional

Create
Delete

The bank account number associated with the ACH payment. This field is only required if the Type field is set to ACH.

Type: string (numeric)
Character limit: 30
Version notes: --
Values: a string of 30 numeric characters or fewer

AchAccountNumberMask

optional

Query
Filter

This is a masked displayable version of the ACH account number, used for security purposes. For example: XXXXXXXXX54321Use this field for ACH payment methods.

Type: string
Character limit: 32
Version notes: --
Values: automatically generated

AchAccountType

conditional

Create
Query
Update
Delete
Filter

The type of bank account associated with the ACH payment. This field is only required if the Type field is set to ACH.

Type: string (enum)
Character limit: 16
Version notes: --
Values

  • BusinessChecking
  • Checking
  • Saving
AchAddress1 conditional

Create
Query
Update
Filter

Line 1 for the ACH address. Required on create for the Vantiv payment gateway. Optional for other gateways.

Type: String
Character limit: 255
Version notes:
Values: an address

AchAddress2 conditional

Create
Query
Update
Filter

Line 2 for the ACH address. Required on create for the Vantiv payment gateway. Optional for other gateways.

Type: String
Character limit: 255
Version notes: 
Values: an address

AchBankName

conditional

Create
Query
Update
Delete
Filter

The name of the bank where the ACH payment account is held. This field is only required if the Type field is set to ACH.

Type: string
Character limit: 70
Version notes: --
Values: a string of 70 characters or fewer

AchCity optional Create
Query
Update

The city of the ACH address. Use this field for ACH payment methods.

Note: This field is only specific to the NMI payment gateway.

Type: string
Character limit: 40
Version notes: 88.0+
Values: a string of 40 characters or fewer

AchCountry optional Create
Query
Update

The country of the ACH address. See View countries or regions for the list of supported country names.

Note: This field is only specific to the NMI payment gateway.

Type: string
Character limit: 44
Version notes: 88.0+
Values: a supported country name

AchPostalCode optional Create
Query
Update

The billing address's zip code. Use this field for an ACH payment method.

Note: This field is only specific to the NMI payment gateway.

Type: string
Character limit: 20
Version notes88.0+
Values: a string of 20 characters or fewer

AchState optional Create
Query
Update

The billing address's state. Use this field if the ACHCountry value is Canada, the US, or any other country with subregions. State names must be spelled in full. For more information, see View subregionsThis field is required only when you define an ACH payment method. Note that this field is only specific to the NMI payment gateway.

Note: This field is only specific to the NMI payment gateway.

Type: string
Character limit: 50
Version notes88.0+
Values: a valid state name

Active

optional

Query
Filter

Specifies whether a payment method is available in Zuora. This field is used to indicate if a payment method is loaded by the system or created by the customer.

  • true: System loaded payment method.
  • false: Customer created payment method.

The default value is false.

Type: boolean
Character limit: 5
Version notes: --
Values: true, false

BankBranchCode

optional

Create
Query
Update
Delete
Filter

The branch code of the bank used for direct debit. Use this field for direct debit payment methods.

Type: string
Character limit: 10
Version notes: --
Values:  string of 10 characters or fewer 

BankCheckDigit

optional

Create
Query
Update
Delete
Filter

The check digit in the international bank account number, which confirms the validity of the account. Use this field for direct debit payment methods.

Type: string
Character limit: 4
Version notes: --
Values:  string of 4 characters or fewer

BankCity

optional

Query
Filter

The city of the direct debit bankUse this field for direct debit payment methods.

Type: string
Character limit:70
Version notes: --
Values:  string of 70 characters or fewer

BankCode

optional

Query
Filter

The sort code or number that identifies the bank. This is also known as the sort code. This field is required for direct debit payment methods.

Type: string
Character limit: 18
Version notes: --
Values:  string of 18 characters or fewer

BankIdentificationNumber

optional

Query
Filter

The first six or eight digits of the payment method's number, such as the credit card number or account number. Banks use this number to identify a payment method.

Type: string
Character limit: 8
Version notes: --
Values:  string of 8 characters or fewer 

BankName

optional

Query
Filter

The name of the direct debit bank. Use this field for direct debit payment methods.

Type: string
Character limit:80
Version notes: --
Values:  string of 80 characters or fewer

BankPostalCode

optional

Query
Filter

The zip code or postal code of the direct debit bankUse this field for direct debit payment methods.

Type: string
Character limit:20
Version notes: --
Values:  string of 20 characters or fewer

BankStreetName

optional

Query
Filter

The name of the street of the direct debit bank. Use this field for direct debit payment methods.

Type: string
Character limit:60
Version notes: --
Values:  string of 60 characters or fewer

BankStreetNumber

optional

Query
Filter

The number of the direct debit bank. Use this field for direct debit payment methods.

Type: string
Character limit:10
Version notes: --
Values:  string of 10 characters or fewer

BankTransferAccountName

optional

Query
Filter

The name on the direct debit bank account. Use this field for direct debit payment methods.

Type: string
Character limit: 60
Version notes: --
Values:  string of 60 characters or fewer

BankTransferAccountNumber

optional

Filter

The number of the customer's bank account. Use this field for direct debit payment methods.

Type: string
Character limit:30
Version notes: --
Values:  string of 30 characters or fewer

BankTransferAccountNumberMask

optional

Query
Filter

This is a masked displayable version of the ACH account number, used for security purposes. For example: XXXXXXXXX54321.

Type: string
Character limit: 32
Version notes: --
Values: automatically generated

BankTransferAccountType

optional

Query
Filter

The type of the customer's bank account. Use this field for direct debit payment methods.

Type: string (enum)
Character limit: 11
Version notes: --
Values:

  • Checking
  • Saving
  • BusinessChecking
  • BusinessSaving

BankTransferType

optional

Query
Filter

Specifies the type of direct debit transfer. The value of this field is dependent on the country of the user. Use this field is used for direct debit payment methods.

Type: string (enum)
Character limit: 20
Version notes: --
Values

  • SEPA
  • AutomatischIncasso (NL)
  • LastschriftDE (Germany)
  • LastschriftAT (Austria)
  • DemandeDePrelevement (FR)
  • DirectDebitUK (UK)
  • Domicil (Belgium)
  • LastschriftCH (CH)
  • RID (Italy)
  • OrdenDeDomiciliacion (Spain)

BusinessIdentificationCode

optional

Create
Query
Update

The business identification code for Swiss direct payment methods that use the Global Collect payment gateway. Use this field only for direct debit payments in Switzerland with Global Collect.

Type: string
Character limit: 11
Version notes: WSDL 35.0+
Valuesstring of 11 characters or fewer

City

optional

Create
Query
Update
Delete
Filter

The city of the customer's address. Use this field for direct debit payment methods.

Type: string
Character limit:80
Version notes: --
Values:  string of 80 characters or fewer

CompanyName optional Create
Query
Update
Delete
Filter

The name of the company. Zuora does not recommend that you use this field.

Type: string
Character limit:80
Version notes: --
Values:  string of 80 characters or fewer

Country

optional

Create
Query
Update
Delete
Filter

The two-letter country code of the customer's address. Use this field for direct debit payment methods. See View countries or regions for the list of supported country codes.

Type: string
Character limit: 2
Version notes
Values: a valid country code

CreatedById

optional

Query
Filter

The user ID of the person who created the PaymentMethod object when there is a login user in the user session.

For payment methods created through Hosted Payment Pages and Payment Method Updater, this field is set to 3 as there is no login user to initiate a user session.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: automatically generated

CreatedDate

optional

Query
Filter

The date when the PaymentMethod object was created in the Zuora system.

Type: date
Character limit: 29
Version notes: WSDL 20.0+
Values: automatically generated

CreditCardAddress1

optional

Create
Query
Update
Delete
Filter

The first line of the card holder's address, which is often a street address or business name. Use this field for credit card and direct debit payment methods.

Type: string
Character limit: 255
Version notes: --
Values: a string of 255 characters or fewer

CreditCardAddress2

optional

Create
Query
Update
Delete
Filter

The second line of the card holder's address. Use this field for credit card and direct debit payment methods.

Type: string
Character limit: 255
Version notes: --
Values: a string of 255 characters or fewer

CreditCardCity

optional

Create
Query
Update
Delete
Filter

The city of the card holder's address. Use this field for credit card and direct debit payment methods

Type: string
Character limit: 40
Version notes: --
Values: a string of 40 characters or fewer

CreditCardCountry

optional

Create
Query
Update
Delete
Filter

The country of the card holder's address. See View countries or regions for the list of supported country names. Use this field for credit card and direct debit payment methods.

Type: string
Character limit: 44
Version notes: --
Values: a supported country name

CreditCardExpirationMonth

optional

Create
Query
Update
Delete
Filter

The expiration month of the credit card or debit card. Use this field for credit card and direct debit payment methods.

Type: int
Character limit: 2
Version notes: --
Values: a two-digit number, 01 - 12

CreditCardExpirationYear

optional

Create
Query
Update
Delete
Filter

The expiration month of the credit card or debit card. Use this field for credit card and direct debit payment methods.

Type: int
Character limit: 4
Version notes: --
Values: a four-digit number

CreditCardHolderName

optional

Create
Query
Update
Delete
Filter

The full name of the card holder. Use this field for credit card and direct debit payment methods.

Type: string
Character limit: 50
Version notes: --
Values: a string of 50 characters or fewer

CreditCardMaskNumber

optional

Query
Filter

A masked version of the credit or debit card number.

Type: string
Character limit: 32
Version notes: --
Values: automatically generated

CreditCardNumber

optional

Create

The credit card or debit card number. This is an insert-only field; it cannot be updated nor queried for security purposes. This field is required only when you define a debit card or credit card payment.

Type: string
Character limit: 16
Version notes: --
Values: a string of 16 characters or fewer

CreditCardPostalCode

optional

Create
Query
Update
Delete
Filter

The billing address's zip code. This field is required only when you define a debit card or credit card payment.

Type: string
Character limit: 20
Version notes: --
Values: a string of 20 characters or fewer

CreditCardSecurityCode

optional

Create
Update
Delete
Filter

The CVV or CVV2 security code. See How do I control what information Zuora sends over to the Payment Gateway? for more information. To ensure PCI compliance, this value is not stored and cannot be queried.

Type: string
Character limit
Version notes: --
Values: a valid CVV or CVV2 security code

CreditCardState

optional

Create
Query
Update
Delete
Filter

The billing address's state. Use this field if the CreditCardCountry value is Canada, the US, or any other country with subregions. State names must be spelled in full. For more information see View subregionsThis field is required only when you define a debit card or credit card payment.

Type: string
Character limit: 50
Version notes: --
Values: a valid state name

CreditCardType

optional

Create
Query
Update
Delete
Filter

The type of credit card or debit card. This field is required only when you define a debit card or credit card payment.

Type: string (enum)
Character limit: 32
Version notes: --
ValuesAmericanExpress, Discover, MasterCard, Visa

DeviceSessionId

optional

Create
Query
Update
Delete
Filter

The session ID of the user when the PaymentMethod was created or updated. Some gateways use this field for fraud prevention. If this field is passed to Zuora, then Zuora passes this field to supported gateways. Currently only Verifi supports this field.

Type: string
Character limit: 255
Version notes: --
Values:

Email

optional

Create
Query
Update
Filter

An email address for the payment method in addition to the bill to contact email address.

Type: string
Character limit: 80
Version notes: --
Values: a string of 80 characters or fewer

ExistingMandate

optional

Create
Query
Update
Delete
Filter

Indicates if the customer has an existing mandate or a new mandate. A mandate is a signed authorization for UK and NL customers. When you are migrating mandates from another system, be sure to set this field correctly. If you indicate that a new mandate is an existing mandate or vice-versa, then transactions fail. This field is used only for the direct debit payment method.

Type: string (enum)
Character limit: 3
Version notes: --
Values: Yes, No

FirstName

optional

Create
Query
Update
Delete
Filter

The customer's first name. This field is used only for the direct debit payment method.

Type: string
Character limit: 30
Version notes: --
Values: a string of 30 characters or fewer

GatewayOptionData optional

Create
Filter

Use this field to pass gateway options.

Type: zns:GatewayOption
Character limit: 255
Version notes: WSDL 18.0+
Values: GatewayOption

IBAN

optional

 

Create
Query
Update
Delete
Filter

The International Bank Account Number. This field is used only for the direct debit payment method.

Type: string
Character limit: 42
Version notes: --
Values: a string of 42 characters or fewer

Id

optional

Query
Filter

The ID of this object. Upon creation, the ID of this object is PaymentMethodId.

Type: zns:ID
Character limit: 32
Version notes: --
Values: automatically generated

IPAddress

optional Create
Query
Update
Delete
Filter

The IP address of the user when the payment method was created or updated. Some gateways use this field for fraud prevention. If this field is passed to Zuora, then Zuora passes this field to supported gateways. Currently, PayPal, CyberSource, Authorize.Net, Verifi, Worldpay, and Allpago support this field.

Type: string
Character limit: 15
Version notes: --
Values: a string of 15 characters or fewer

LastFailedSaleTransactionDate

optional

Query
Filter

The date of the last failed attempt to collect payment with this payment method.

Type: date
Character limit: 29
Version notes: --
Values: automatically generated

LastName

optional

Create
Query
Update
Delete
Filter

The customer's last name. This field is used only for the direct debit payment method.

Type: string
Character limit: 70
Version notes: --
Values: a string of 70 characters or fewer

LastTransactionDateTime

optional

Create
Query
Update
Delete
Filter

The date of the most recent transaction.

Type: date
Character limit: 29
Version notes: --
Valuesa valid date and time value

LastTransactionStatus

optional

Query
Filter

The status of the most recent transaction.

Type: string (enum)
Character limit: 39
Version notes: --
Values: automatically generated

MandateCreationDate

optional

Create
Query
Update
Delete
Filter

The date when the mandate was created. A mandate is a signed authorization for UK and NL customers. This field is used only for the direct debit payment method.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29
Version notes: --
Valuesa valid date and time value

MandateID

optional

Create
Query
Update
Delete
Filter

The ID of the mandate. A mandate is a signed authorization for UK and NL customers. This field is used only for the direct debit payment method.

Type: string
Character limit: 36
Version notes: --
Values: a string of 36 characters or fewer

MandateReceived

optional

Create
Query
Update
Delete
Filter

Indicates if  the mandate was received. A mandate is a signed authorization for UK and NL customers. This field is used only for the direct debit payment method.

Type: string (enum)
Character limit: 3
Version notes: --
Values: Yes, No (case-sensitive)

MandateUpdateDate

 

optional

Create
Query
Update
Delete
Filter

The date when the mandate was last updated. A mandate is a signed authorization for UK and NL customers. This field is used only for the direct debit payment method.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29
Version notes: --
Valuesa valid date and time value

MaxConsecutivePaymentFailures

optional

Create
Query
Update
Delete
Filter

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

Type: short
Character limit:
Version notes: --
Values: a valid number

MitConsentAgreementRef

optional

Create

Specifies your reference for the stored credential consent agreement that you have established with the customer. Only applicable if you set the MitProfileAction field.

Type: string
Character limit: 128
Version notes: WSDL 94.0+

MitConsentAgreementSrc

conditional

Create

Required if you set the MitProfileAction field.

Type: string
Version notes: WSDL 94.0+
Values: External

MitNetworkTransactionId

optional

Create

Specifies the ID of a network transaction. Only applicable if you set the MitProfileAction field to Persist.

Type: string
Character limit: 128
Version notes: WSDL 94.0+

MitProfileAction

optional

Create

If you set this field, Zuora creates a stored credential profile within the payment method.

  • Activate - Use this value if you are creating the stored credential profile after receiving the customer's consent.

    Zuora will create the stored credential profile then send a cardholder-initiated transaction (CIT) to the payment gateway to valdiate the stored credential profile. If the CIT succeeds, the status of the stored credential profile will be Active. If the CIT does not succeed, Zuora will not create a stored credential profile.

    If the payment gateway does not support the stored credential transaction framework, the status of the stored credential profile will be Agreed.

  • Persist - Use this value if the stored credential profile represents a stored credential profile in an external system. The status of the payment method's stored credential profile will be Active.

Type: string
Version notes: WSDL 94.0+
Values: Activate, Persist

MitProfileAgreedOn optional Create

The date on which the profile is agreed. The date format is yyyy-mm-dd.

          Type: date
          Version notes: WSDL 94.0
          Values: a valid date

MitProfileType

conditional

Create

Required if you set the MitProfileAction field.

Type: string
Version notes: WSDL 94.0+
Values
Recurring

Name

optional

Query
Filter

The name of the payment method. This value can be one of the following:

  • For system generated payment methods: A payment method as listed in Payment Settings. For a list of supported payment methods, see Set Payment Methods
  • For bank transfer methods created from the Hosted Payment Pages: "Bank Transfer + bankAccountNumberMask". For example, Bank Transfer **********1111.

The Name field for all the other electronic payment methods is empty.

Note: You cannot specify names for new payment methods in the SOAP API.

Type: string
Character limit: 51
Version notes: --
Values: automatically generated

NumConsecutiveFailures

optional

Create
Query
Update
Filter

The number of consecutive failed payment for this payment method. It is reset to 0 upon successful payment. You can use the API to update the field value to 0.

Type: int
Character limit
Version notes: read-only field for WSDL 27.0 and older
Values: a positive whole number

PaymentMethodStatus

optional

Query
Update*
Filter

This field is used to indicate the status of the payment method created within an account.

It is set to Active on creation.

Type: string
Character limit: 6
Version notes: --
Values: Active or Closed

*Update() functionality added in WSDL 47.

PaymentMethodStatus should not be used in the create() call.

You can only set this field to Closed via the update() call.

PaymentRetryWindow

optional

Create
Query
Update
Delete
Filter

The retry interval setting, which prevents making a payment attempt if the last failed attempt was within the last specified number of hours. This field is required if the UseDefaultRetryRule field value is set to false.

Type: short
Character limit: 4
Version notes: --
Values: a whole number between 1 and 1000, exclusive

PaypalBaid

optional

Create
Query
Filter

The PayPal billing agreement ID, which is a contract between two PayPal accounts. Typically, the selling party initiates a request to create a BAID, and sends it to buying party for acceptance. The seller can keep track of the BAID and use it for future charges against the buyer. This field is required when defining a PayPal payment method.

Type: string
Character limit: 64
Version notes: --
Values: a string of 64 characters or fewer

PaypalEmail

optional

Create
Query
Filter

The email address associated with the account holder's PayPal account or of the PayPal account of the person paying for the service. This field is required only when you define a PayPal payment method.

Type: string
Character limit: 80
Version notes: --
Values: a string of 80 characters or fewer

PaypalPreapprovalKey

optional

Create
Query
Filter

PayPal's Adaptive Payments API key. Zuora does not create this key, nor does it call PayPal to generate it. You must use PayPal's Adaptive Payments' API to generate this key, and then pass it to Zuora. Zuora uses this key to authorize future payments to PayPal's Adaptive Payments API. This field is required when you use PayPal Adaptive Payments gateway.

Type: string
Character limit: 32
Version notes: --
Values: a valid PayPal Adaptive Payment pre-approval key

PaypalType

optional

Create
Query
Filter

Specifies the PayPal gateway: PayFlow Pro (Express Checkout) or Adaptive Payments. This field is required when you use PayPal Adaptive Payments or Payflow Pro (Express Checkout) gateways.

Type: string (enum)
Character limit: 32
Version notes: --
ValuesExpressCheckout, AdaptivePayments

Phone

optional

Create
Query
Update
Delete
Filter

The phone number that the account holder registered with the bank. This field is used for credit card validation when passing to a gateway.

Type: string
Character limit: 40
Version notes: --
Values: a string of 40 characters or fewer

PostalCode

optional

Create
Query
Update
Delete
Filter

The zip code of the customer's address. This field is used only for the direct debit payment method.

Type: string
Character limit: 20
Version notes: --
Values: a string of 20 characters or fewer

SkipValidation

optional

Create

If you set this field to true, Zuora will create the payment method without making Authorization calls to the gateway. The static field value check will remain as is.

Type: boolean
Character limit: 5
Version notes: --
Values: true, false

State

optional

Create
Query
Update
Delete
Filter

The state of the customer's address. This field is used only for the direct debit payment method.

Type: string
Character limit: 70
Version notes: --
Values: a string of 70 characters or fewer

StreetName

optional

Create
Query
Update
Delete
Filter

The street name of the customer's address. This field is used only for the direct debit payment method.

Type: string
Character limit: 100
Version notes: --
Values: a string of 100 characters or fewer

StreetNumber

optional

Create
Query
Update
Delete
Filter

The street number of the customer's address. This field is used only for the direct debit payment method.

Type: string
Character limit: 30
Version notes: --
Values: a string of 30 characters or fewer

TokenId

optional

Create
Query

A gateway unique identifier that replaces sensitive payment method data or represents a gateway's unique customer profile. When TokenId is used to represent a customer profile, then SecondTokenId is conditionally required for representing the underlying tokenized payment method. TokenId is required for the CC Reference Transaction payment method.

Type: string
Character limit: 255
Version notes: WSDL 48.0+
Values: a string of 255 characters or fewer

SecondTokenId

optional

Create
Query
Update

A gateway unique identifier that replaces sensitive payment method data. SecondTokenId is conditionally required only when TokenID is being used to represent a gateway customer profile. TokenID is being used to represent a gateway customer profile. SecondTokenId is used in the CC Reference Transaction payment method. 

Type: string
Character limit: 64
Version notes: WSDL 58.0+
Values: a string of 64 characters or fewer

TotalNumberOfErrorPayments

required

Query
Filter

The number of error payments that used this payment method.

Type: int
Character limit
Version notes: --
Values: automatically generated

TotalNumberOfProcessedPayments

required

Query
Filter

The number of successful payments that used this payment method.

Type: int
Character limit
Version notes: --
Values: automatically generated

Type

required

Create
Query
Filter

The type of payment method. 

Type: string (enum)
Character limit
Version notes: --
ValuesACHBankTransferCash, Check, CreditCard, CreditCardReferenceTransaction, DebitCard, Other, PayPal, WireTransfer

UpdatedById

optional

Query
Filter

The ID of the user who last updated the payment method.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: automatically generated

UpdatedDate

optional

Query
Filter

The date when the payment method was last updated.

Type: date
Character limit: 29
Version notes: --
Values: automatically generated

UseDefaultRetryRule

required

Create
Query
Update
Delete
Filter

Determines whether to use the default retry rules configured in the Z-Payments settings. Set this to true to use the default retry rules. Set this to false to set the specific rules for this payment method. If you set this value to false, then the fields, PaymentRetryWindow and MaxConsecutivePaymentFailures, are required.

Type: boolean
Character limit: 5
Version notes: --
Valuestruefalse

Additional Field Detail

Active

Specifies whether a payment method is available in Zuora. The default value is false.

The Active field value indicates 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.

Id

The ID of this object. Every object has a unique identifier that Zuora automatically assigns upon creation. You use this ID later when you work with the object. For example, if you send an amend() call to modify an existing subscription, then you need to include the specific Subscriptionobject's ID with the call.

The ID for the PaymentMethod object is PaymentMethodId.

Type

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 or PayPal information.
  • If the payment type is CreditCard, then only populate the credit card fields. Do not include PayPal or ACH information.
  • If the payment type is Paypal, then only populate the PayPal fields. Do not include credit card or ACH information.
  • The one exception is the DebitCard type: If the payment type is DebitCard, then all the credit card fields are required.

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

LastTransactionStatus

The following items are the possible values for the LastTransactionStatus field:

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

PaymentRetryWindow

The retry interval setting, which prevents making a payment attempt if the last failed attempt was within the last specified number of hours. 

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 1 p.m. and the retry interval is 4 hours, then a payment run at 2 p.m. doesn't attempt a payment. A payment run at 6 p.m. does attempt a payment. If you want to retry once a day, then we recommend 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 the UseDefaultRetryRule field value is set to false.