CRUD: Create a payment method

Use this operation to create either a payment method associated with a specific customer account, or an orphan payment method that is not associated with any customer account. The orphan payment method must be associated with a customer account within 10 days. Otherwise, it will be deleted.

Request
query Parameters
rejectUnknownFields
boolean
Default: false

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:

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

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

header Parameters
Idempotency-Key
string <= 255 characters

Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types.

With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.

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 <= 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 (').

Request Body schema: application/json
required
AccountId
string

The ID of the customer account associated with this payment method. To create an orphan payment method that is not associated with any customer account, you do not need to specify this field during creation. However, you must associate the orphan payment method with a customer account within 10 days. Otherwise, this orphan payment method will be deleted.

AchAbaCode
string

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

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. This field is only required if the Type field is set to ACH.

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

AchAccountNumber
string

The bank account number associated with the ACH payment. This field is only required if the Type field is set to ACH. Character limit: 30 Values: a string of 30 numeric characters or fewer

AchAccountType
string

The type of bank account associated with the ACH payment. This field is only required if the Type field is set to ACH. 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. This field is required for creating a payment method for the Vantiv payment gateway. Character limit: 255 Values: an address

AchAddress2
string

Line 2 for the ACH address. This field is required for creating a payment method for the Vantiv payment gateway. Character limit: 255 Values: an address

AchBankName
string

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. 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. It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing. 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 for the list of supported country names. Use this field for ACH methods. Note: This field is only specific to the NMI payment gateway. It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing. Character limit: 40 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 20 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. 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. This field is required 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: a 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. This field is required for the following bank transfer payment methods:

  • Direct Debit UK (Bacs)
  • Denmark Direct Debit (Betalingsservice)
  • Direct Debit NZ (DirectDebitNZ)
  • Pre-Authorized Debit (PAD)
BankTransferAccountName
string

The name on the customer's bank account. This field is required if the Type field is set to BankTransfer.

Character limit: 60

Values: a string of 60 characters or fewer

BankTransferAccountNumber
string

The number of the customer's bank account. This field is required if the Type field is set to BankTransfer.

Character limit: 30

Values: a string of 30 characters or fewer

BankTransferAccountNumberMask
string

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

Character limit: 32

Values: automatically generated

BankTransferType
string <= 20 characters

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: a string of 11 characters or fewer

City
string

The city of the customer's address. Use this field for direct debit payment methods. It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing. Character limit:80 Values: a string of 80 characters or fewer

CompanyName
string <= 80 characters

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. This field is required if the Type field is set to BankTransfer, and the BankTransferType field is set to any of the following values:

  • Autogiro
  • Betalingsservice
  • DirectDebitUK
  • DirectEntryAU
  • DirectDebitNZ
  • PAD

It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.

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. It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing. Character limit: 40 Values: a string of 40 characters or fewer

CreditCardCountry
string

The country of the card holder's address. It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.

CreditCardExpirationMonth
integer <int32>

The expiration month of the credit card or debit card. This field is required if the Type field is set to CreditCard or DebitCard. Character limit: 2 Values: a two-digit number, 01 - 12

CreditCardExpirationYear
integer <int32>

The expiration month of the credit card or debit card. This field is required if the Type field is set to CreditCard or DebitCard. Character limit: 4 Values: a four-digit number

CreditCardHolderName
string

The full name of the card holder. This field is only required if the Type field is set to CreditCard or DebitCard.

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

CreditCardNumber
string

Credit card number, a string of up to 16 characters. This field is required if the Type field is set to CreditCard or DebitCard. This field can only be set when creating a new payment method; it cannot be queried or updated.

CreditCardPostalCode
string

The billing address's zip code. 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? for more information. To ensure PCI compliance, this value is not stored and cannot be queried.

CreditCardState
string

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

CreditCardType
string

The type of the credit card. This field is required if the Type field is set to CreditCard or DebitCard.

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.

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

object

A field used to pass gateway options. Zuora allows you to pass in special gateway-specific parameters for payments through the gateway integrations that support gateway options.

For each of these special parameters, you supply the name-value pair and Zuora passes it to the gateway. This allows you to add functionality that's supported by a specific gateway but currently not supported by Zuora.

Zuora sends all the information that you specified to the gateway. If you specify any unsupported gateway option parameters, they will be ignored without error prompts.

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 for the following bank transfer payment methods:

  • Denmark Direct Debit (Betalingsservice)
  • Sweden Direct Debit (Autogiro)

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
Default: false

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 <date-time>

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

MandateCreationDate
string <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

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 <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

MaxConsecutivePaymentFailures
integer

Specifies the number of allowable consecutive failures Zuora attempts with the payment method before stopping. When the UseDefaultRetryRule field is set to false, this field is only required if the PaymentRetryWindow field is not defined. Values: a valid number

MitConsentAgreementRef
string <= 128 characters

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

MitConsentAgreementSrc
string

Required if you set the MitProfileAction field. If you do not specify the MitProfileAction field, Zuora will automatically create a stored credential profile for the payment method, with the default value External set to this field.

Value: "External"
MitNetworkTransactionId
string <= 128 characters

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

MitProfileAction
string

Specifies how Zuora creates and activates a stored credential profile. If you do not specify this field, Zuora will automatically create a stored credential profile for the payment method, with the default value Activate set to this field.

Enum: "Activate" "Persist"
MitProfileAgreedOn
string <date>

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

MitProfileType
string

Required if you set the MitProfileAction field. If you do not specify the MitProfileAction field, Zuora will automatically create a stored credential profile for the payment method, with the default value Recurring set to this field.

Value: "Recurring"
NumConsecutiveFailures
integer <int32> [ 0 .. 100 ]

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

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. When the UseDefaultRetryRule field is set to false, this field is only required if the MaxConsecutivePaymentFailures field is not defined. Character limit: 4 Values: a whole number between 1 and 1000, exclusive

PaypalBaid
string

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 only required if the Type field is set to PayPal. Character limit: 64 Values: a string of 64 characters or fewer

PaypalEmail
string

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 only required if the Type field is set to PayPal. Character limit: 80 Values: a string of 80 characters or fewer

PaypalPreapprovalKey
string

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 only required if you use PayPal Adaptive Payments gateway. Character limit: 32 Values: a valid PayPal Adaptive Payment pre-approval key

PaypalType
string

Specifies the PayPal gateway: PayFlow Pro (Express Checkout) or Adaptive Payments. This field is only required if you use PayPal Adaptive Payments or Payflow Pro (Express Checkout) gateways. Character limit: 32 Values: ExpressCheckout, AdaptivePayments

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

SkipValidation
boolean

If you set this field to false, Zuora will send an authorization request to the payment gateway. If the authorization fails, the Create Payment Method request will fail as well. If the user knows that the card number or token is valid, we recommend disabling this feature because authorization requests to the card network incur additional processing fees. Currently, Zuora sends all authorizations as keyed entries. If you set this field to true, the authorization request is not sent. Character limit: 5 Values: true or false

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

TokenId
string

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, SecondTokenId is conditionally required for representing the underlying tokenized payment method. TokenId is required for the CC Reference Transaction payment method. The values for the tokenId and secondTokenId fields differ for gateways. For more information, see the Knowledge Center article specific to each gateway that supports the CC Reference Transaction payment method. Character limit: 255 Values: a string of 255 characters or fewer

Type
required
string

The type of payment method.

If you want to create an Amazon Pay payment method, specify CreditCardReferenceTransaction for this field.

If you want create a custom payment method, specify the name of the custom payment method type. This type is only available if the Universal Payment Connector and Open Payment Method services are enabled. See Set up custom payment gateways and payment methods for details.

Enum: "ACH" "BankTransfer" "CreditCard" "CreditCardReferenceTransaction" "DebitCard" "PayPal"
UseDefaultRetryRule
boolean

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

currencyCode
string

The currency used for payment method authorization.

If this field is not specified, currency specified for the account is used for payment method authorization. If no currency is specified for the account, the default currency of the account is then used.

property name*
additional property
any

Custom fields of the payment method. The name of each custom field has the form customField__c. Custom field names are case sensitive. See Manage Custom Fields for more information.

Responses
200
400
401
post/v1/object/payment-method
Request samples
application/json
{
  • "AccountId": "8ad09be48db5aba7018db604776d4854",
  • "Type": "CreditCard",
  • "CreditCardType": "Visa",
  • "CreditCardNumber": "4111111111111111",
  • "CreditCardExpirationMonth": 12,
  • "CreditCardExpirationYear": 2020,
  • "CreditCardHolderName": "Amy Lawrence"
}
Response samples
application/json
{
  • "Success": true,
  • "Id": "2c93808457d787030157e03220ec4fad"
}