This API Reference contains the API operations that we no longer recommend you use.
Although we do not recommend these API operations, you can continue to use these API operations if you have integrated with them. You are not required to make changes to your existing integration.
For more information about this change, see this Community post.
Actions are operations that are batch in nature. For example, the "create", "update", "delete", and other operations allow changes to up-to 50 objects at a time. The "query" operation will return up-to 2000 result records back at a time, before requiring additional pages of data to be returned via a subsequent "queryMore" operation.
The default WSDL version for Actions is 79. If you want to change the WSDL version, set the X-Zuora-WSDL-Version header. To find out in which WSDL version a particular object or field was introduced, see Zuora SOAP API Version History.
Note: Actions do not support the Invoice Settlement feature. This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. Actions also do not support the Orders feature.
Some operations in this section are similar to each other, but are provided for different use scenarios. You should choose the one that best suits your needs.
For example, the Create account operation is used to create an account with a credit card payment method, a bill-to contact, and optionally an sold-to contact or an associated subscription. If you want to create an account without creating any associated objects such as subscriptions, use CRUD: Create Account instead.
If you want to create an account and the associated subscription at the same time without providing credit card information, use the Subscribe action.
You can use amendments to modify subscriptions. However, Zuora recommends you to use the Create an order operation to do so.
This section contains the CRUD bill run operations, including:
The Charge Revenue Summary represents a summary of revenue amounts from all revenue schedules on the whole subscription charge. For example, revenue for one-time setup charges, recurring charges, and overages.
You can list all details of a charge revenue summary or retrieve a charge revenue summary by charge ID through the REST API.
A communication profile enables you to send specific event-driven notifications to targeted customer accounts. For more information, see Communication profiles.
You can manage communication profiles using the REST API:
Establishes a connection to the Zuora REST API service based on a valid user credentials.
Note: This is a legacy REST API. Zuora recommends you to use OAuth for authentication instead.
You can create, update, and retrieve custom document properties for a billing document. For example, a document property can be a custom name used for files generated for billing documents. Billing documents include invoices, credit memos, and debit memos.
Note: You can manage document properties for credit memos and debit memos only if you have the <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement" target="_blank">Invoice Settlement</a> feature enabled.
An entity represents a business unit that operates independently and can sell products to multiple countries. Each entity has its own Zuora environment in which the entity users can perform business operations independent of the other entities. In a multi-entity hierarchy, an entity can share certain business objects with the other entities. Users that are created in an entity can be granted access to the other entities with different roles and permissions.
Note: Entities are available only if you have the <a href="https://knowledgecenter.zuora.com/Billing/Tenant_Management/Multi-entity" target="_blank">Multi-entity</a> feature enabled. If you want to have access to the Multi-entity feature, submit a request at <a href=“http://support.zuora.com/” target=“_blank”>Zuora Global Support</a>.
If you want to share business objects across entities, you have to set up a connection between the source entity and the target entity first.
Note: Entity connections are available only if you have the <a href="https://knowledgecenter.zuora.com/Billing/Tenant_Management/Multi-entity" target="_blank">Multi-entity</a> feature enabled. If you want to have access to the Multi-entity feature, submit a request at <a href=“http://support.zuora.com/” target=“_blank”>Zuora Global Support</a>.
You can export items from Zuora to CSV or HTML files, such as large data sets, invoices, payments, and so on. Use the Export object and Export ZOQL queries to create an export file that you can download and use for charting, reporting, accounting, or for other business intelligence uses.
When you export data from Zuora, each exported file is available for download for 7 days. Export objects older than 90 days are automatically deleted.
After you have created a feature, you can add features to the products and subscriptions to enhance your product offerings.
To create features in the product catalog and use them in subscriptions and Zuora Quotes, you need to enable the following:
A Hash-based Message Authentication Code (HMAC) signature is a form of a digital signature. HMAC signatures start with a secret key that is shared between the sender and the recipient.
You can use the operation contained in this section to generate the unique signature and token values that are used to process CORS-enabled API calls.
An invoice adjustment modifies an existing invoice. You use an invoice adjustment to change the entire invoice. For example, you can apply a late fee to the invoice balance.
An invoice adjustment differs from an invoice item adjustment. An invoice item adjustment affects an individual charge or line item on an invoice. An invoice adjustment affects the invoice at the header-level.
Note: Invoice Adjustment is deprecated on Production in WSDL version 64.0. Zuora recommends that you use the Invoice Item Adjustment to adjust invoices. If you have the <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement" target="_blank">Invoice Settlement</a> feature enabled, this object is deprecated and only available for backward compatibility.
Invoice item adjustments allow you to adjust the invoice details, including taxes at the charge level, and have those adjustments reported in the system under the same accounting code as the items that are being adjusted.
Note: The <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement" target="_blank">Invoice Settlement</a> feature is a replacement for Invoice Item Adjustments. We recommend that you enable Invoice Settlement to take advantage of the improved functionalities. If you have the Invoice Settlement feature enabled, the Invoice Item Adjustments feature is deprecated and invoice item adjustments are not presented in the UI. If you have to export data for invoice item adjustments, use <a href="https://knowledgecenter.zuora.com/Billing/Reporting/D_Data_Sources_and_Exports/D_Generate_a_Data_Source_Export" target="_blank">Data Source</a>, <a href="https://knowledgecenter.zuora.com/Central_Platform/Query/Data_Query" target="_blank">Data Query</a>, or REST API.
Invoices provides information about customers' accounts for invoices, for examples, dates, status, and amounts.
For more information about invoices, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/IA_Invoices/A1_Invoice_Introduction" target="_blank">Invoice</a>.
You can use the Retrieve a payment gateway transaction log operation to retrieve log data about all transactions processed through your setup payment gateways.
Note: This legacy API operation is no longer under active development. For more features, it is strongly recommended to use the Create a payment method operation.
You can create a credit card payment method for a customer account or an orphan credit card payment method that is not associated with any customer account.
This API call is CORS Enabled. Use client-side JavaScript to invoke the call.
If you use this operation to create credit card payment methods instead of using the iFrame of Hosted Payment Pages, you are subject to PCI-compliance audit requirements.
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.
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.
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.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
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 (').
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.
ID of the customer account. To create an orphan payment method that is not associated with any customer account, you can skip this field. As soon as the account information is available, associate the payment method with an account through the Update a payment method operation.
Container for cardholder information. If provided, Zuora will only use this information for this card. Otherwise, Zuora will use the account''s existing bill-to contact information for this card.
Credit card number, a string of up to 16 characters. This field can only be set when creating a new payment method; it cannot be queried or updated.
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.
Specify true to make this card the default payment method; otherwise, omit this parameter to keep the current default payment method.
The field used to pass gateway-specific parameters and parameter values.
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.
Specifies your reference for the stored credential consent agreement that you have established with the customer. Only applicable if you set the mitProfileAction field.
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.
Specifies the ID of a network transaction. Only applicable if you set the mitProfileAction field to Persist.
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.
The date on which the profile is agreed. The date format is yyyy-mm-dd.
Required if you set the mitProfileAction field. Indicates the type of the stored credential profile to process recurring or unsecheduled transactions. 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.
The number of consecutive failed payments for this payment method. It is reset to 0 upon successful payment.
The CVV or CVV2 security code for the credit card or debit card. Only required if changing expirationMonth, expirationYear, or cardHolderName. To ensure PCI compliance, this value isn't stored and can't be queried.
Custom fields of the payment method. The name of each custom field has the form <code>customField__c</code>. Custom field names are case sensitive. See Manage Custom Fields for more information.
curl -i -X POST \
https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/payment-methods/credit-cards \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: string' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string' \
-d '{
"accountKey": "8ad09be48db5aba7018db604776d4854",
"creditCardType": "Visa",
"creditCardNumber": "4111111111111111",
"expirationMonth": 10,
"expirationYear": 2021
}'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/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
{ "paymentMethodId": "2c92c8f83dcbd8b1013dcce1d6a60", "success": true }
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.
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.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
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 (').
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.
The full name as it appears on the card, e.g., "John J Smith", 50 characters or less.
Specify "true" to make this card the default payment method; otherwise, omit this parameter to keep the current default payment method.
The field used to pass gateway-specific parameters and parameter values.
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.
The number of consecutive failed payments for this payment method. It is reset to 0 upon successful payment.
The CVV or CVV2 security code for the credit card or debit card. Only required if changing expirationMonth, expirationYear, or cardHolderName. To ensure PCI compliance, this value isn't stored and can't be queried.
Custom fields of the payment method. The name of each custom field has the form <code>customField__c</code>. Custom field names are case sensitive. See Manage Custom Fields for more information.
curl -i -X PUT \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/payment-methods/credit-cards/{payment-method-id}' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Content-Type: application/json' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string' \
-d '{
"cardHolderName": "Amy Lawrence"
}'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/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
{ "paymentMethodId": "2c92c8f83dcbd8b1013dcce1d6a600ce", "success": true }
This REST API reference describes how to retrieve all credit card information for the specified customer account.
The response includes details of credit or debit cards for the specified customer account. Card numbers are masked. For example:
************1234Though you can also send requests for bank transfer, ACH, or other supported payment methods, the response will not include effective details of these payment methods.
The index number of the page that you want to retrieve. This parameter is dependent on pageSize. You must set pageSize before specifying page. For example, if you set pageSize to 20 and page to 2, the 21st to 40th records are returned in the response.
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.
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.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
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 (').
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.
curl -i -X GET \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/payment-methods/credit-cards/accounts/{account-key}?page=1&pageSize=20' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string'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/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
{ "nextPage": "https://rest.zuora.com/v1/payment-methods/credit-cards/accounts/A00001115?page=2&pageSize=2", "creditCards": [ { … }, { … } ], "success": true }
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.
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.
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.
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.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
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.
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 (').
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 can skip this field. As soon as the account information is available, associate the payment method with an account through the Update a payment method operation.
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
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
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
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:
BusinessCheckingBusinessSavingCheckingSavingLine 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
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
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
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
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
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
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
The branch code of the bank used for direct debit. This field is required for the following bank transfer payment methods:
Autogiro)DirectDebitNZ)PAD)Character limit: 10
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
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:
Bacs)Betalingsservice)DirectDebitNZ)PAD)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
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
This is a masked displayable version of the ACH account number, used for security purposes. For example: XXXXXXXXX54321.
Character limit: 32
Values: automatically generated
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)
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
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
The name of the company.
Zuora does not recommend that you use this field.
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:
AutogiroBetalingsserviceDirectDebitUKDirectEntryAUDirectDebitNZPADIt 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.
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
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
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
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.
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
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
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
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.
The billing address's zip code. Character limit: 20 Values: a string of 20 characters or fewer
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.
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.
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.
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:
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
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
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
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.
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
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.
The unique identity number of the customer account. This field is required for the following bank transfer payment methods:
It is a string of 12 characters for a Swedish identity number, and a string of 10 characters for a Denish identity number.
Whether the customer account is a company.
Zuora does not recommend that you use this field.
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
The date of the most recent transaction. Character limit: 29 Values: a valid date and time value
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
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
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)
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
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
Specifies your reference for the stored credential consent agreement that you have established with the customer. Only applicable if you set the MitProfileAction field.
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.
Specifies the ID of a network transaction. Only applicable if you set the MitProfileAction field to Persist.
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.
The date on which the profile is agreed. The date format is yyyy-mm-dd.
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.
The number of consecutive failed payments for this payment method. It is reset to 0 upon successful payment.
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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.
Custom fields of the payment method. The name of each custom field has the form <code>customField__c</code>. Custom field names are case sensitive. See Manage Custom Fields for more information.
curl -i -X POST \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/object/payment-method?rejectUnknownFields=false' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: string' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string' \
-d '{
"AccountId": "8ad09be48db5aba7018db604776d4854",
"Type": "CreditCard",
"CreditCardType": "Visa",
"CreditCardNumber": "4111111111111111",
"CreditCardExpirationMonth": 12,
"CreditCardExpirationYear": 2020,
"CreditCardHolderName": "Amy Lawrence"
}'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/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
{ "Success": true, "Id": "2c93808457d787030157e03220ec4fad" }
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.
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.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
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.
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 -i -X GET \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/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'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/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
The ID of the customer account associated with this payment method. This field is not required for the account ID.
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
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
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
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:
BusinessCheckingBusinnessSavingCheckingSavingLine 1 for the ACH address. Required on create for the Vantiv payment gateway. Optional for other gateways. Character limit: Values: an address
Line 2 for the ACH address. Required on create for the Vantiv payment gateway. Optional for other gateways. Character limit: Values: an address
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
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
The branch code of the bank used for direct debit. Character limit: 10 Values: string of 10 characters or fewer
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
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
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
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
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
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
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
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
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
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
This is a masked displayable version of the bank account number, used for security purposes. For example: XXXXXXXXX54321. Character limit: 32 Values: automatically generated
The type of the customer's bank account. Use this field for direct debit payment methods. Character limit: 11 Values: DirectDebit
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
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
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
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
The date when the PaymentMethod object was created in the Zuora system. Character limit: 29 Values: automatically generated
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
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
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
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
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
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
A masked version of the credit or debit card number. Character limit: 32 Values: automatically generated
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
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.
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.
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
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
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
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
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
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.
The date of the last failed attempt to collect payment with this payment method. Character limit: 29 Values: automatically generated
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
The date of the most recent transaction. Character limit: 29 Values: a valid date and time value
The status of the most recent transaction. Character limit: 39 Values: automatically generated
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
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
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)
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
Specifies the number of allowable consecutive failures Zuora attempts with the payment method before stopping. Values: a valid number
The number of consecutive failed payments for this payment method. It is reset to 0 upon successful payment.
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
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
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
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
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
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
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
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
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
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
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
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
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
The number of error payments that used this payment method. Character limit: Values: automatically generated
The number of successful payments that used this payment method. Character limit: Values: automatically generated
The type of payment method.
The ID of the user who last updated the payment method. Character limit: 32 Values: automatically generated
The date when the payment method was last updated. Character limit: 29 Values: automatically generated
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
{ "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 }
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.
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.
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.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
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.
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 (').
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.
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
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
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:
BusinessCheckingBusinessSavingCheckingSavingLine 1 for the ACH address. Required on create for the Vantiv payment gateway. Optional for other gateways.
Character limit: Values: an address
Line 2 for the ACH address. Required on create for the Vantiv payment gateway. Optional for other gateways.
Character limit: Values: an address
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
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
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.
Character limit: 44 Values: a supported country name
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
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
The branch code of the bank used for direct debit. Use this field for the following bank transfer payment methods:
Autogiro)DirectDebitNZ)PAD)Character limit: 10
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
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:
Bacs)Betalingsservice)DirectDebitNZ)PAD)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)
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
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
The name of the company.
Zuora does not recommend that you use this field.
The two-letter country code of the customer's address. Use this field for the following bank transfer payment methods:
AutogiroBetalingsserviceDirectDebitUKDirectEntryAUDirectDebitNZPADThe 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
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
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
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
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
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
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
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. Values: a valid CVV or CVV2 security code
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.
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.
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:
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
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
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
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
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.
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.
Whether the customer account is a company.
Zuora does not recommend that you use this field.
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
The date of the most recent transaction. Character limit: 29 Values: a valid date and time value
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
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
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)
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
Specifies the number of allowable consecutive failures Zuora attempts with the payment method before stopping. Values: a valid number
The number of consecutive failed payments for this payment method. It is reset to 0 upon successful payment.
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
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
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
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
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
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
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
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
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
Custom fields of the payment method. The name of each custom field has the form <code>customField__c</code>. Custom field names are case sensitive. See Manage Custom Fields for more information.
curl -i -X PUT \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/object/payment-method/{id}?rejectUnknownFields=false' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Content-Type: application/json' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string' \
-d '{
"CreditCardCountry": "United States",
"CreditCardState": "CA"
}'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/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
{ "Success": true, "Id": "2c93808457d787030157e02fced332a2" }
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.
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.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
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.
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 -i -X DELETE \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/object/payment-method/{id}' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string'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/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
{ "success": true, "id": "2c93808457d787030157e02fcc8e329f" }
This section contains the Generate a quote document operation that should be only used from Zuora Quotes.
This operation generates a quote document and returns the generated document URL. You can directly access the generated quote file through the returned URL.
A rate plan charge tier is part of a subscription or an amendment to a subscription, and it comes from a product rate plan charge tier. A rate plan charge tier holds the prices for a rate plan charge. Each rate plan charge has at least one tier associated with it.
Rate plan charge tiers are sometimes called subscription rate plan charge tiers to distinguish them from product rate plan charge tiers. Rate plan charge tiers that are part of an amendment are sometimes called amendment rate plan charge tiers for the same reason. However, the object name is RatePlanChargeTier, not SubscriptionRatePlanChargeTier nor AmendmentRatePlanChargeTier: these latter two names don't exist.
A rate plan charge is part of a subscription or an amendment to a subscription, and it comes from a product rate plan charge. Like a product and its product rate plan charges, a subscription can have one or more rate plan charges. Rate plan charges represent the actual charges for the rate plans or services that you sell.
Rate plan charges are sometimes called subscription rate plan charges to distinguish them from product rate plan charges. Rate plan charges that are part of an amendment are sometimes called amendment rate plan charges for the same reason. The object name is RatePlanCharge – not SubscriptionRatePlanCharge nor AmendmentRatePlanCharge.
A rate plan is part of a subscription or an amendment to a subscription, and it comes from a product rate plan. Like a product and its product rate plans, a subscription can have one or more rate plans. Rate plans are sometimes called subscription rate plans. Rate plans that are part of an amendment are sometimes called amendment rate plans.
Rate plans represent a price or a collection of prices for a service you sell. An individual rate plan contains all charges specific to a particular subscription.
This section contains the CRUD: Retrieve a refund invoice payment operation. You can use this operation to retrieve information from Refund Invoice Payment and associated invoices, payments, and accounts.
This section contains the CRUD: Retrieve a refund transaction log operation. This operation allows you to export a log of all transactions from Zuora to the gateway for the refund.
Zuora allows you to issue and track refunds on payments. Similar to external payments, users can enter external refunds to track refunds that have been performed outside of Zuora Payments (for example, by issuing a check). In addition, you can make electronic refunds using our supported payment gateways, which will automatically refund money to the customer.
The Zuora Reporting API enables you to access reports that you have created in the Zuora UI, manage report runs, and export the results of report runs.
The endpoints of the Reporting API are the same as the endpoints of Zuora REST API. The following table provides some endpoints as reference:
| Environment | API Endpoint |
|---|---|
| API Sandbox (US Cloud Data Center 1) | https://rest.sandbox.na.zuora.com |
| Production (US Cloud Data Center 1) | https://rest.na.zuora.com |
| API Sandbox (US Cloud Data Center 2) | https://rest.apisandbox.zuora.com |
| Production (US Cloud Data Center 2) | https://rest.zuora.com |
| API Sandbox (EU Data Center) | https://rest.sandbox.eu.zuora.com |
| Production (EU Data Center) | https://rest.eu.zuora.com |
| US Central Sandbox | https://rest.test.zuora.com |
| EU Central Sandbox | https://rest.test.eu.zuora.com |
| APAC Developer & Central Sandbox | https://rest.test.ap.zuora.com |
| APAC Production | https://rest.ap.zuora.com |
Historically, the endpoints of the Reporting API were different from the endpoints of the Zuora REST API.
Note that you are still able to use the following endpoints, but it is unrecommended and you can only use username and password to authenticate to the Reporting API. We recommend you to use OAuth to authenticate to the Reporting API. OAuth only works with new endpoints. The endpoints of the Reporting API were:
| Environment | API Endpoint |
|---|---|
| API Sandbox (US Cloud Data Center 1) | https://zconnect.sandbox.na.zuora.com/api/rest/v1 |
| Production (US Cloud Data Center 1) | https://zconnect.na.zuora.com/api/rest/v1 |
| API Sandbox (US Cloud Data Center 2) | https://zconnectsandbox.zuora.com/api/rest/v1 |
| Production (US Cloud Data Center 2) | https://zconnect.zuora.com/api/rest/v1 |
| API Sandbox (EU Data Center) | https://zconnect.sandbox.eu.zuora.com/api/rest/v1 |
| Production (EU Data Center) | https://zconnect.eu.zuora.com/api/rest/v1 |
| US Central Sandbox | https://zconnect-services0001.test.zuora.com/api/rest/v1 |
| EU Central Sandbox | https://zconnect-services0002.test.eu.zuora.com/api/rest/v1 |
| APAC Developer & Central Sandbox | https://zconnect-services0003.test.ap.zuora.com |
| APAC Production | http://zconnect-prod05.ap.zuora.com |
A revenue event is a record or audit trail about a change to a revenue schedule. When you manually distribute revenue schedule, if no change is made to the revenue schedule, no revenue events will not be created.
A revenue event is comprised of:
The Entitlements settings must be enabled to use this operation. Access to the Entitlements feature requires a specific edition of Zuora. See Zuora Editions for details.
A subscription is a product or service that has recurring charges, such as a monthly flat fee or charges based on usage. Subscriptions can also include one-time charges, such as activation fees. Every subscription must be associated with an account. At least one active account must exist before any subscriptions can be created.
For more information, see <a href="https://knowledgecenter.zuora.com/Billing/Subscriptions/Subscriptions" target="_blank">Subscriptions</a>.
The TaxationItem object is used to add a tax amount to an invoice item. In the typical use case, the tax amount that you specify in the object is calculated by <a href="https://knowledgecenter.zuora.com/Billing/Taxes/A_Zuora_Tax" target="_blank">Z-Tax</a> or a third-party tax engine such as <a href="https://knowledgecenter.zuora.com/Billing/Taxes/Direct_Avalara_Integration" target="_blank">Avalara</a> or <a href="https://knowledgecenter.zuora.com/Billing/Taxes/Additional_resources_on_taxes/AA_Connect_Tax_Engines" target="_blank">Connect tax engine</a>.
Changes that you make with this object affect the product charges in your product catalog, but not the charges in existing subscriptions.
You can view all transactions associated with an account, including:
A unit of measure (UOM) is the definable unit that you measure when determining charges. For example, if a customer's subscription rate plan includes 20 licenses, then 20 is the quantity and license is the unit that the quantity measures.
You can customize the units of measure (UOM) your company uses to measure the use of your services; for example, minutes, people, seats, and licenses can all be units of measure.
This section contains the legacy API operations for Usage.
For the "Retrieve a usage record" operation, we recommend that you use the following Object Query operations instead: