Skip to content

CRUD: Retrieve a payment method

Request

Path
idstringrequired

Object id

Query
fieldsstring

Object fields to return

Headers
Accept-Encodingstring

Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

Content-Encodingstring

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Authorizationstring

The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.

Zuora-Entity-Idsstring

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Idstring, <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

cURL
curl -i -X GET \
  'https://rest.zuora.com/v1/object/payment-method/{id}?fields=string' \
  -H 'Accept-Encoding: string' \
  -H 'Authorization: string' \
  -H 'Content-Encoding: string' \
  -H 'Zuora-Entity-Ids: string' \
  -H 'Zuora-Track-Id: string'

Responses

Headers
Content-Encodingstring

This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.

Note that only the following MIME types support gzipped responses:

  • application/json
  • application/xml
  • text/html
  • text/csv
  • text/plain
RateLimit-Limitstring

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

RateLimit-Remainingnumber

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

RateLimit-Resetnumber

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

Zuora-Request-Idstring, = 36 characters

The Zuora internal identifier of the API call. You cannot control the value of this header.

Zuora-Track-Idstring, <= 64 characters

A custom identifier for tracing the API call. If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. Otherwise, Zuora does not set this header.

Bodyapplication/json
AccountIdstring

The ID of the customer account associated with this payment method. This field is not required for the account ID.

AchAbaCodestring

The nine-digit routing number or ABA number used by banks. Use this field for ACH payment methods. Character limit: 9 Values: a string of 9 characters or fewer

AchAccountNamestring

The name of the account holder, which can be either a person or a company. Use this field for ACH payment methods. Character limit: 70 Values: a string of 70 characters or fewer

AchAccountNumberMaskstring

This is a masked displayable version of the ACH account number, used for security purposes. For example: XXXXXXXXX54321. Use this field for ACH payment methods. Character limit: 32 Values: automatically generated

AchAccountTypestring

The type of bank account associated with the ACH payment. Use this field for ACH payment methods. When creating an ACH payment method on Adyen, this field is required by Zuora but it is not required by Adyen. To create the ACH payment method successfully, specify a real value for this field if you can. If it is not possible to get the real value for it, specify any of the allowed values as a dummy value, Checking preferably. Character limit: 16 Values:

  • BusinessChecking
  • BusinnessSaving
  • Checking
  • Saving
AchAddress1string

Line 1 for the ACH address. Required on create for the Vantiv payment gateway. Optional for other gateways. Character limit: Values: an address

AchAddress2string

Line 2 for the ACH address. Required on create for the Vantiv payment gateway. Optional for other gateways. Character limit: Values: an address

AchBankNamestring

The name of the bank where the ACH payment account is held. Use this field for ACH payment methods. When creating an ACH payment method on Adyen, this field is required by Zuora but it is not required by Adyen. To create the ACH payment method successfully, specify a real value for this field if you can. If it is not possible to get the real value for it, specify a dummy value. Character limit: 70 Values: a string of 70 characters or fewer

Activeboolean

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. Character limit: 5 Values: true, false

BankBranchCodestring

The branch code of the bank used for direct debit. Character limit: 10 Values: string of 10 characters or fewer

BankCheckDigitstring

The check digit in the international bank account number, which confirms the validity of the account. Use this field for direct debit payment methods. Character limit: 4 Values: string of 4 characters or fewer

BankCitystring

The city of the direct debit bank. Use this field for direct debit payment methods. Character limit:70 Values: string of 70 characters or fewer

BankCodestring

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. Character limit: 18 Values: string of 18 characters or fewer

BankIdentificationNumberstring

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. Character limit: 8 Values: string of 8 characters or fewer

BankNamestring

The name of the direct debit bank. Use this field for direct debit payment methods. Character limit:80 Values: string of 80 characters or fewer

BankPostalCodestring

The zip code or postal code of the direct debit bank. Use this field for direct debit payment methods. Character limit:20 Values: string of 20 characters or fewer

BankStreetNamestring

The name of the street of the direct debit bank. Use this field for direct debit payment methods. Character limit:60 Values: string of 60 characters or fewer

BankStreetNumberstring

The number of the direct debit bank. Use this field for direct debit payment methods. Character limit:10 Values: string of 10 characters or fewer

BankTransferAccountNamestring

The name on the customer's bank account. Use this field for bank transfer payment methods. Character limit: 60 Values: string of 60 characters or fewer

BankTransferAccountNumberstring

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

Character limit: 30 Values: a string of 30 characters or fewer

BankTransferAccountNumberMaskstring

This is a masked displayable version of the bank account number, used for security purposes. For example: XXXXXXXXX54321. Character limit: 32 Values: automatically generated

BankTransferAccountTypestring

The type of the customer's bank account. Use this field for direct debit payment methods. Character limit: 11 Values: DirectDebit

BankTransferTypestring, <= 20 characters

The type of direct debit transfer.

BusinessIdentificationCodestring

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. Character limit: 11 Values: string of 11 characters or fewer

Citystring

The city of the customer's address. Use this field for direct debit payment methods. Character limit:80 Values: string of 80 characters or fewer

CompanyNamestring

The name of the company.

Countrystring

The two-letter country code of the customer's address. Use this field for bank transfer payment methods. Character limit: 2 Values: a valid country code

CreatedByIdstring

The user ID of the person who created the PaymentMethod object when there is a login user in the user session. In Hosted Payment Method and Zuora Checkout pages, this field is set to 3 as there is no login user to initiate a user session. Character limit: 32 Values: automatically generated

CreatedDatestring, (date-time)

The date when the PaymentMethod object was created in the Zuora system. Character limit: 29 Values: automatically generated

CreditCardAddress1string

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. Character limit: 255 Values: a string of 255 characters or fewer

CreditCardAddress2string

The second line of the card holder's address. Use this field for credit card and direct debit payment methods. Character limit: 255 Values: a string of 255 characters or fewer

CreditCardCitystring

The city of the card holder's address. Use this field for credit card and direct debit payment methods Character limit: 40 Values: a string of 40 characters or fewer

CreditCardCountrystring

The country of the card holder's address.

CreditCardExpirationMonthinteger, (int32)

The expiration month of the credit card or debit card. Use this field for credit card and direct debit payment methods. Character limit: 2 Values: a two-digit number, 01 - 12

CreditCardExpirationYearinteger, (int32)

The expiration month of the credit card or debit card. Use this field for credit card and direct debit payment methods. Character limit: 4 Values: a four-digit number

CreditCardHolderNamestring

The full name of the card holder. Use this field for credit card and direct debit payment methods. Character limit: 50 Values: a string of 50 characters or fewer

CreditCardMaskNumberstring

A masked version of the credit or debit card number. Character limit: 32 Values: automatically generated

CreditCardPostalCodestring

The billing address's zip code. This field is required only when you define a debit card or credit card payment. Character limit: 20 Values: a string of 20 characters or fewer

CreditCardStatestring

The billing address's state. Use this field is if the CreditCardCountry value is either Canada or the US. State names must be spelled in full.

CreditCardTypestring

The type of the credit card.

Possible values include Visa, MasterCard, AmericanExpress, Discover, JCB, and Diners. For more information about credit card types supported by different payment gateways, see Supported Payment Gateways.

DeviceSessionIdstring

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. Character limit: 255

Emailstring

An email address for the payment method in addition to the bill to contact email address. Character limit: 80 Values: a string of 80 characters or fewer

ExistingMandatestring

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. Character limit: 3 Values: Yes or No

FirstNamestring

The customer's first name. This field is used only for the direct debit payment method. Character limit: 30 Values: a string of 30 characters or fewer

IBANstring

The International Bank Account Number. This field is used only for the direct debit payment method. Character limit: 42 Values: a string of 42 characters or fewer

IPAddressstring

The IPv4 or IPv6 information of the user when the payment method was created or updated. Gateways use this field for fraud prevention. If this field is passed to Zuora, then Zuora passes this field to supported gateways. If the IP address length is beyond 45 characters, a validation error occurs.

Idstring

Object identifier.

IdentityNumberstring

The unique identity number of the customer account.

IsCompanyboolean

Whether the customer account is a company.

LastFailedSaleTransactionDatestring, (date-time)

The date of the last failed attempt to collect payment with this payment method. Character limit: 29 Values: automatically generated

LastNamestring

The customer's last name. This field is used only for the direct debit payment method. Character limit: 70 Values: a string of 70 characters or fewer

LastTransactionDateTimestring, (date-time)

The date of the most recent transaction. Character limit: 29 Values: a valid date and time value

LastTransactionStatusstring

The status of the most recent transaction. Character limit: 39 Values: automatically generated

MandateCreationDatestring, (date)

The date when the mandate was created, in yyyy-mm-dd format. A mandate is a signed authorization for UK and NL customers. This field is used only for the direct debit payment method. Character limit: 29

MandateIDstring

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. Character limit: 36 Values: a string of 36 characters or fewer

MandateReceivedstring

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. Character limit: 3 Values: Yes or No (case-sensitive)

MandateUpdateDatestring, (date)

The date when the mandate was last updated, in yyyy-mm-dd format. A mandate is a signed authorization for UK and NL customers. This field is used only for the direct debit payment method. Character limit: 29

MaxConsecutivePaymentFailuresinteger

Specifies the number of allowable consecutive failures Zuora attempts with the payment method before stopping. Values: a valid number

Namestring

The name of the payment method.

NumConsecutiveFailuresinteger, (int32), [ 0 .. 100 ]

The number of consecutive failed payments for this payment method. It is reset to 0 upon successful payment.

PaymentMethodStatusstring

This field is used to indicate the status of the payment method created within an account. It is set to Active on creation. Character limit: 6 Values: Active or Closed

PaymentRetryWindowinteger

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. Character limit: 4 Values: a whole number between 1 and 1000, exclusive

PaypalBaidstring

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. Character limit: 64 Values: a string of 64 characters or fewer

PaypalEmailstring

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. Character limit: 80 Values: a string of 80 characters or fewer

PaypalPreapprovalKeystring

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. Character limit: 32 Values: a valid PayPal Adaptive Payment pre-approval key

PaypalTypestring

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. Character limit: 32 Values: ExpressCheckout or AdaptivePayments

Phonestring

The phone number that the account holder registered with the bank. This field is used for credit card validation when passing to a gateway. Character limit: 40 Values: a string of 40 characters or fewer

PostalCodestring

The zip code of the customer's address. This field is used only for the direct debit payment method. Character limit: 20 Values: a string of 20 characters or fewer

SecondTokenIdstring

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. SecondTokenId is used in the CC Reference Transaction payment method. Character limit: 64 Values: a string of 64 characters or fewer

Statestring

The state of the customer's address. This field is used only for the direct debit payment method. Character limit: 70 Values: a string of 70 characters or fewer

StreetNamestring

The street name of the customer's address. This field is used only for the direct debit payment method. Character limit: 100 Values: a string of 100 characters or fewer

StreetNumberstring

The street number of the customer's address. This field is used only for the direct debit payment method. Character limit: 30 Values: a string of 30 characters or fewer

TokenIdstring

A gateway unique identifier that replaces sensitive payment method data or represents a gateway's unique customer profile. TokenId is required for the CC Reference Transaction payment method. Character limit: 255 Values: a string of 255 characters or fewer

TotalNumberOfErrorPaymentsinteger, (int32)

The number of error payments that used this payment method. Character limit: Values: automatically generated

TotalNumberOfProcessedPaymentsinteger, (int32)

The number of successful payments that used this payment method. Character limit: Values: automatically generated

Typestring

The type of payment method.

Enum:"ACH""ApplePay""BankTransfer""Cash""Check""CreditCard""CreditCardReferenceTransaction""DebitCard""Other""PayPal"
UpdatedByIdstring

The ID of the user who last updated the payment method. Character limit: 32 Values: automatically generated

UpdatedDatestring, (date-time)

The date when the payment method was last updated. Character limit: 29 Values: automatically generated

UseDefaultRetryRuleboolean

Determines whether to use the default retry rules configured in the Zuora 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. Character limit: 5 Values: t``rue, false

Response
{ "CreditCardExpirationMonth": 12, "CreditCardAddress1": "312 2nd Ave W", "Id": "2c93808457d787030157e0314e8145d7", "CreditCardExpirationYear": 2020, "UpdatedDate": "2016-10-20T05:45:10.000+02:00", "CreditCardCity": "Seattle", "CreditCardState": "Washington", "AccountId": "2c93808457d787030157e0314c0945d4", "Type": "CreditCard", "UpdatedById": "2c93808457d787030157e0312ef1445e", "CreditCardCountry": "United States", "AchAddress1": "312 2nd Ave W", "CreditCardType": "Visa", "CreatedById": "2c93808457d787030157e0312ef1445e", "CreditCardPostalCode": "98119", "CreditCardHolderName": "Somebody", "CreatedDate": "2016-10-20T05:45:10.000+02:00", "TotalNumberOfProcessedPayments": 1, "PaymentMethodStatus": "Active", "NumConsecutiveFailures": 7, "TotalNumberOfErrorPayments": 0, "CreditCardMaskNumber": "************1111", "LastTransactionStatus": "Approved", "LastTransactionDateTime": "2016-10-20T05:45:10.000+02:00", "UseDefaultRetryRule": true, "BankIdentificationNumber": "411111", "IdentityNumber": "", "IsCompany": false, "CompanyName": "", "Active": false }