Skip to main content

Set up and configure a Stripe payment gateway instance

Zuora

Set up and configure a Stripe payment gateway instance

  1. Last updated
  2. Save as PDF

Set up and configure a Stripe payment gateway instance by using the information in this article, including prerequisites, configuration procedure, descriptions of the configuration fields, and references for testing the payment gateway.

Prerequisites

  • Enable the Stripe payment gateway integration for your tenant. See Enable payment gateway integrations for your tenant for instructions.
  • The following requirements are specific to the BACS payment method:
    • You must configure a custom SUN ID in your merchant account for processing payments. It can be configured in the Stripe Dashboard under Payment Settings. By default, your integration with Stripe will use Stripe’s SUN ID, which indicates that Stripe is the Merchant of Record. 
    • Before using BACS payment methods, ensure that you have completed the following tasks in Stripe. For more information, see Stripe Docs.
      • Contact Stripe Support and enable BACS payment method.
      • Configure mandate ID and debit notifications.

Procedure

Take the following steps to configure the Stripe payment gateway in Zuora:

  1. Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway. The gateway list is displayed.
  2. On the Configure Gateway Instance tab, select Stripe v2 or Stripe v1 from the Gateway Type drop-down list.
  3. Click Create Gateway.
  4. Configure the gateway settings as needed. See the sections below for details about each setting.
  5. Once you have entered the necessary information, click Save Gateway Information.

Configuration fields

Common configuration fields

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

Specific configuration fields

The following fields are specific to the Stripe payment gateway.

Credentials

Field Description
Access Token (required)

Select the created OAuth 2.0 token from the Access Token dropdown 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.

Enable Level 2/Level 3 Processing

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.

Downgrade failed L3 payment attempts

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.

ProductCode Custom Field API Name

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.

Auto-capture IP Address

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.

Disable Stripe Radar risk assessments on payment 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.

Additional metadata

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.

Test the configuration

We recommend that you test your payment gateway by using both your payment gateway's test and production (live) environments.  Once you have completed testing in the gateway's test environment, it is recommended that you perform a test in your live production environment with a real credit card. If there are any differences in the configuration of your testing and production accounts, testing in production ensures your production merchant account is set up properly and can successfully connect to the production environment.

You can use the test card information and testing scenarios provided by the gateway vendor to test your integration. See the following documents on the Stripe Docs website for details: