home

Zuora Payments

Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableRelease NotesBasicsEntitlementsSupport and policies
Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableRelease NotesBasicsEntitlementsSupport and policies

Welcome to Zuora Product Documentation

Explore our rich library of product information

Show Contents

thumbnailZuora Payments

Set up and configure a Stripe payment gateway instance

Configuration fields

Learn about the common fields required for configuring payment gateways, including specific settings for the Stripe payment gateway.

There are some common fields you must complete for every gateway configuration. We recommend reviewing Setting Up Payment Gateways for information on these fields:

  • Name

  • Use Gateway Test Environment : If you want to test your transactions in Stripe test mode , select this checkbox. Connecting to Stripe sandbox is not supported due to a limitation of Stripe OAuth Connect .

  • Cards Accepted

  • Default Authorization Amount :

    • For requirements on the amount, see Minimum and maximum charge amounts for more information.

    • For Stripe v2, the value specified in this field will not be used in credit card verification. Stripe manages the authorization process and the amount used during credit card verification. Zuora does not have control over the verificaiton process.

  • Verify new payment method

  • Verify updated payment method

When using tokenized payment methods with the Stripe payment gateway, the Verify new payment method and Verify updated payment method settings must be enabled.

The following fields are specific to the Stripe payment gateway.

Field

Description

Access Token (required)

Select the created OAuth 2.0 token from the Access Token dropdown list.

If Use Gateway Test Environment is selected in the Basic Information section, select the token created using the test credentials from this list.

To create a token or view all available tokens, navigate to Payments Settings > Gateway Authentication . For more information about how to create OAuth tokens in Zuora, see Payment Gateway Authentication .

Secret Key (read-only)

Only available for the gateway instances created before Zuora Billing Release 296.

Determines if the transaction will go through the merchant's live or test account. You can find your Secret key by navigating to Developers > API Keys in your Stripe merchant account .

Publishable Key (read-only)

Only available for the gateway instances created before Zuora Billing Release 296.

This field is specific to Stripe v2. It can be found on your Stripe account settings page. You can find your Stripe API Publishable key by navigating to Developers > API Keys in your Stripe merchant account .

Note that for the Stripe gateway instances created before Zuora Billing Release 296, the previously stored Secret Key and Publishable Key credentials can continue to work, but you cannot update them anymore. If you want to switch to the OAuth authentication mode, you can create an OAuth token and select it from the Access Token dropdown list. The OAuth 2.0 authentication is then enabled for all subsequent requests.

Before configuring this gateway setting, ensure that you have enabled the Level 2 or Level 3 data processing for your Stripe merchant account. Contact Stripe Support to get it enabled.

Select this check box if you want to enable the Level 2 or Level 3 processing for Visa or Mastercard credit card transactions on the Zuora side.

With this setting enabled, all of the following additional fields are sent to Stripe during the transaction:

Transaction type

Fields

Digital goods

  • merchant_reference : A unique value that is assigned by the merchant to identify the order. Also known as an "Order ID”. A maximum of 25 characters is allowed.

  • customer_reference : A unique value that is assigned by the merchant to identify the customer. Also known as “Customer ID”. A maximum of 17 characters is allowed.

  • line_items . It can contain multiple line items. For each item, the following fields are included:

    • product_code : A unique identifier for the product. A maximum of 12 characters is allowed. This field maps to the custom field value you configure in the ProductCode Custom Field API Name gateway setting. If that gateway setting is not specified, the value for this field will default to the Product SKU.

    • product_description : A description of the product. A maximum of 26 characters is allowed.

    • unit_cost : The cost of the product in cents, as a non-negative number.

    • quantity : The number of items of this type sold, as a non-negative number.

    • tax_amount : The amount of tax in cents, as a non-negative number.

    • discount_amount : The amount of the item discount if a discount is applicable, as a non-negative number.

Physical goods that require shipment

  • shipping_address_zip : The end customer’s U.S. shipping ZIP code.

  • shipping_from_zip : The merchant’s U.S. shipping ZIP code.

  • shipping_amount : The shipping cost in cents, as a non-negative number.

Level 2 and Level 3 Customer Billing Details

  • name

  • address_line1

  • city

  • state

  • country

  • zip_code

For more information about Zuora's support for Level 3 and Level 2 data, see Level 2 and Level 3 Card Data .

This setting allows for downgrading Level 3 processing to transactions without Level 3 data. With both this checkbox and the Enable Level 2/Level 3 Processing check box selected, an immediate payment attempt without Level 3 data will be made when the payment with Level 3 data fails to ensure collection against invoices.

Some billing and payment rules in Zuora do not align with those in Stripe, such as support for multiple decimal places, negative invoice items, etc. The initial Level 3 payment attempt will likely fail in these cases. In these scenarios, it is strongly recommended to implement downgrading Level 3 processing so that the failed transaction due to Level 3 data processing will result in the creation of an immediate payment retry to ensure that the transaction is still collected. Zuora is working with Stripe on these limitations to address them.

The value specified in this field will be mapped to the product_code field that is sent to Stripe. If this field is not specified, the product_code field will default to the product SKU.

This setting is only available for Stripe v2 .

With this check box selected, Zuora will automatically send the IP address to Stripe through Payment Pages when a new payment method is created. It facilitates the use of Stripe's Radar service to prevent fraudulent transactions.

This setting is only available for Stripe v2.

This setting is cleared by default. If this setting is selected, Stripe Radar risk assessments will be skipped on recurring transactions. This setting does not apply to one-time payments initiated through the hosted payment pages.

This setting is only available for Stripe v2.

Enter the payment description information in this field, and it will be passed to the gateway through the paymentIntents.description request field when making Credit Card and Credit Card Reference payments. The maximum length for this field is 512 characters.

Statement descriptions are displayed on your customers’ card or account statements, helping them recognize transactions. To define statement descriptions for transactions on Stripe v2, you can use the following approaches:

  • To use a dynamic description, configure the Select the source field for Soft Descriptors to appear on statements payment rule .

  • To use a static description, specify the softDescriptor field when creating or authorizing a payment through the API operations. The value specified through the API operation overrides the Select the source field for Soft Descriptors to appear on statements value.

If no value is provided through either of the above methods, the descriptor field is excluded from the transaction request.

The following sections describe how descriptors are populated for different payment method types.

If the Select the source field for Soft Descriptors to appear on statements payment rule is configured, the value retrieved from the selected source is passed to the gateway through the paymentIntents.statement_descriptor_suffix request field when creating or authorizing a payment.

The descriptor displayed on your customer’s statement is formed by concatenating the following values:

  • The value of the statement_descriptor_prefix field that is configured in Stripe. The static prefix, known as Shortened Descriptor, can be configured on the Stripe dashboard .

  • The value of the statement_descriptor_suffix field submitted by Zuora .

  • An asterisk (*) and a space between the above two values.

The following table describes an example:

Field

Value

statement_descriptor_prefix

RUNCLUB

statement_descriptor_suffix

OCT MARATHON

Descriptor on customer’s statement

RUNCLUB* OCT MARATHON

The maximum character length allowed for the statement_descriptor_suffix field is affected by the value in the statement_descriptor_prefix field. If the concatenated descriptor exceeds the maximum allowed characters, the full prefix and the partial suffix by cutting off the excess characters are used.

For example, if the total length of the concatenated descriptor is no more than 22 characters including the asterisk and the space, and if the prefix is 7 characters, the dynamic suffix can contain up to 13 characters.

If the Select the source field for Soft Descriptors to appear on statements payment rule is configured, the value retrieved from the selected source is passed to the gateway through the paymentIntents.statement_descriptor request field.

This setting is only available for Stripe v2 . You can define your customized metadata in the Additional Metadata section for the following objects when you configure a Stripe v2 gateway. You can use this data for further analysis, reporting, or building custom Stripe Radar rules to enhance your fraud protection. Note that 3DS2 operations do not support passing the customized metadata.

  • Payment - Your self-defined metadata for payment transactions will be added to the metadata tag in the request body and passed to the gateway, in addition to the payment number. Metadata of the following transaction types is supported for the Payment object.

    • Credit Card

    • CC Reference Transaction

    • Bank Transfer

    • ACH

  • Payment Method - Your self-defined metadata for payment method validation will be added to the metadata tag in the request body and passed to the gateway. Metadata of the following transaction types is supported for the Payment Method object.

    • Credit Card

    • Bank Transfer

To add a customized field, complete the following steps:

  1. On the New Gateway or Edit Gateway page, click add new metadata in the Additional Metadata section.
  2. In the Metadata Key field, enter the metadata field name by following these rules:

    • The field name must be unique.

    • Only alphanumeric characters and underscores are allowed.

    • See Stripe documentation for details about the field and character limits.

  3. Select a field from the list to indicate the metadata value.

Last updated: December 3, 2025