# CRUD: Update a payment method

Updates a payment method.

Endpoint: PUT /v1/object/payment-method/{id}
Version: 2025-12-17

## Header parameters:

  - `Accept-Encoding` (string)
    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-Encoding` (string)
    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.

  - `Authorization` (string)
    The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.

  - `Zuora-Entity-Ids` (string)
    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-Id` (string)
    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 (').

## Query parameters:

  - `rejectUnknownFields` (boolean)
    Specifies whether the call fails if the request body contains unknown fields.
With rejectUnknownFields set to true, Zuora returns a 400 response if
the request body contains unknown fields. The body of the 400 response is:

json
{
    "message": "Error - unrecognised fields"
}


By default, Zuora ignores unknown fields in the request body.

## Path parameters:

  - `id` (string, required)
    Object id

## Request fields (application/json):

  - `AccountId` (string)
    The ID of the customer account associated with this payment method.

Note: If a payment method was created without an account ID associated, you can update the payment method to specify an account ID in this operation. 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 this operation.

  - `AchAbaCode` (string)
    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

  - `AchAccountName` (string)
    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

  - `AchAccountType` (string)
    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
- BusinessSaving
- Checking
- Saving

  - `AchAddress1` (string)
    Line 1 for the ACH address. Required on create for the Vantiv payment gateway. Optional for other gateways.

Character limit: Values: an address

  - `AchAddress2` (string)
    Line 2 for the ACH address. Required on create for the Vantiv payment gateway. Optional for other gateways.

Character limit: Values: an address

  - `AchBankName` (string)
    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

  - `AchCity` (string)
    The city of the ACH address. Use this field for ACH payment methods. Note: This field is only specific to the NMI payment gateway.
Character limit: 40 Values: a string of 40 characters or fewer

  - `AchCountry` (string)
    The country of the ACH address. See [Country Names and Their ISO Standard 2- and 3-Digit Codes](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/D_Country%2C_State%2C_and_Province_Codes/A_Country_Names_and_Their_ISO_Codes) for the list of supported country names. Use this field for ACH methods.
Note: This field is only specific to the NMI payment gateway.

Character limit: 44 Values: a supported country name

  - `AchPostalCode` (string)
    The billing address's zip code. This field is required only when you define an ACH payment method. Note: This field is only specific to the NMI payment gateway.

Character limit: 20 Values: a string of 40 characters or fewer

  - `AchState` (string)
    The billing address's state. Use this field is if the ACHCountry value is either Canada or the US. State names must be spelled in full. For more information, see the list of [supported state names](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/D_Country%2C_State%2C_and_Province_Codes/B_State_Names_and_2-Digit_Codes). This field is required only when you define an ACH payment method. Note: This field is only specific to the NMI payment gateway.

Character limit: 50 Values: a valid state name

  - `BankBranchCode` (string)
    The branch code of the bank used for direct debit. Use this field for the following bank transfer payment methods:
  - Sweden Direct Debit (Autogiro)
  - Direct Debit NZ (DirectDebitNZ)
  - Pre-Authorized Debit (PAD)

Character limit: 10

  - `BankCheckDigit` (string)
    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

  - `BankCode` (string)
    The sort code or number that identifies the bank. This is also known as the sort code. Use this field for the following bank transfer payment methods:
  - Direct Debit UK (Bacs)
  - Denmark Direct Debit (Betalingsservice)
  - Direct Debit NZ (DirectDebitNZ)
  - Pre-Authorized Debit (PAD)

  - `BankTransferType` (string)
    The type of direct debit transfer. The value of this field is dependent on the country of the user. This field is only required if the Type field is set to BankTransfer.

Values: 

  - SEPA

  - DirectEntryAU (Australia)

  - DirectDebitUK (UK)

  - Autogiro (Sweden)

  - Betalingsservice (Denmark)

  - DirectDebitNZ (New Zealand)
  
  - PAD (Canada)
   
  - AutomatischIncasso (Netherlands)

  - LastschriftDE (Germany)

  - LastschriftAT (Austria)

  - DemandeDePrelevement (France)

  - Domicil (Belgium)

  - LastschriftCH (Switzerland)

  - RID (Italy)

  - OrdenDeDomiciliacion (Spain)

  - `BusinessIdentificationCode` (string)
    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

  - `City` (string)
    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

  - `CompanyName` (string)
    The name of the company.

Zuora does not recommend that you use this field.

  - `Country` (string)
    The two-letter country code of the customer's address. Use this field for the following bank transfer payment methods:
  - Autogiro
  - Betalingsservice
  - DirectDebitUK
  - DirectEntryAU
  - DirectDebitNZ
  - PAD

  - `CreditCardAddress1` (string)
    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

  - `CreditCardAddress2` (string)
    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

  - `CreditCardCity` (string)
    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

  - `CreditCardCountry` (string)
    The country of the card holder's address.
    Example: "United States"

  - `CreditCardExpirationMonth` (integer)
    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

  - `CreditCardExpirationYear` (integer)
    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

  - `CreditCardHolderName` (string)
    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

  - `CreditCardPostalCode` (string)
    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

  - `CreditCardSecurityCode` (string)
    The CVV or CVV2 security code. See [How do I control what information Zuora sends over to the Payment Gateway?](https://knowledgecenter.zuora.com/kb/How_do_I_control_information_sent_to_payment_gateways_when_verifying_payment_methods%3F) for more information. To ensure PCI compliance, this value is not stored and cannot be queried.
Values: a valid CVV or CVV2 security code

  - `CreditCardState` (string)
    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.
    Example: "CA"

  - `CreditCardType` (string)
    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](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways).

  - `DeviceSessionId` (string)
    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 Values:

  - `Email` (string)
    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

  - `ExistingMandate` (string)
    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, No

  - `FirstName` (string)
    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

  - `IBAN` (string)
    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

  - `IPAddress` (string)
    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.

  - `IdentityNumber` (string)
    The unique identity number of the customer account. 

This field is required only if the BankTransferType field is set to Autogiro or Betalingsservice. It is a string of 12 characters for a Swedish identity number, and a string of 10 characters for a Denish identity number.

  - `IsCompany` (boolean)
    Whether the customer account is a company.

Zuora does not recommend that you use this field.

  - `LastName` (string)
    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

  - `LastTransactionDateTime` (string)
    The date of the most recent transaction.
Character limit: 29 Values: a valid date and time value

  - `MandateCreationDate` (string)
    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

  - `MandateID` (string)
    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

  - `MandateReceived` (string)
    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, No (case-sensitive)

  - `MandateUpdateDate` (string)
    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

  - `MaxConsecutivePaymentFailures` (integer)
    Specifies the number of allowable consecutive failures Zuora attempts with the payment method before stopping.
Values: a valid number

  - `NumConsecutiveFailures` (integer)
    The number of consecutive failed payments for this payment method. It is reset to 0 upon successful payment.

  - `PaymentMethodStatus` (string)
    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

  - `PaymentRetryWindow` (integer)
    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

  - `Phone` (string)
    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

  - `PostalCode` (string)
    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

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

  - `State` (string)
    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

  - `StreetName` (string)
    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

  - `StreetNumber` (string)
    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

  - `UseDefaultRetryRule` (boolean)
    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: true or false

## Response 200 fields (application/json):

  - `Id` (string)
    Example: "2c93808457d787030157e030232f3748"

  - `Success` (boolean)
    Example: true

## Response 401 fields (application/json):

  - `message` (string)
    Error message.

If the error message is "Authentication error", ensure that the Authorization request header contains valid authentication credentials, then retry the request. See [Authentication](https://developer.zuora.com/rest-api/general-concepts/authentication/) for more information.

If the error message is "Failed to get user info", retry the request.