Skip to main content

Stripe Payment Gateway

Zuora

Stripe Payment Gateway

The Stripe payment gateway allows individuals and businesses to accept payments over the internet. 

Supported Gateway Versions

Zuora provides two Stripe gateway integration versions, Stripe v1 and Stripe v2. The following table lists the major functional differences between Stripe v1 and Stripe v2:

Functionalities Stripe v1 Stripe v2
Supported payment methods
  • Credit Cards (Visa, Mastercard, American Express, Discover, JCB, and Diners Club)
  • Credit Card Reference
  • ACH
  • Credit Cards (Visa, Mastercard, American Express, Discover, JCB, and Diners Club)
  • Credit Card Reference
  • ACH
  • SEPA
Support 3DS2 through Payment Pages 2.0? No Yes
Support stored credential transactions? No  Yes
Support Level 2 / Level 3 data processing? No  Yes
Support ACH Tokenization? No Yes

Stripe v2 includes support for the Stored Credential Transaction framework of Visa, Mastercard, and American Express.

Currently, only existing Stripe tokens are supported as a Credit Card Reference payment method type. Creating tokens in Zuora is not supported.

Configure the Stripe Payment Gateway

  1. Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway
  2. Select Stripe v1 or Stripe v2 from the Gateway Type drop-down menu.
  3. Click create gateway.
  4. Configure the gateway settings as needed.
  5. Once you have entered the necessary information, click save gateway information.

Stripe v2 config page.png

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 (Does not apply to Stripe)
  • Secret Key
  • Cards Accepted
  • Default Authorization Amount: Must not be less than 0.50, in any currency. See Minimum and maximum charge amounts for more information.
  • Verify new payment method (optional)
  • Verify updated payment method (optional)

When using ACH payment method with the Stripe payment gateway, the Verify new payment method and Verify updated payment method check boxes are required to be selected. 

Gateway Specific Configuration Fields

The following fields are specific to the Stripe payment gateway.

Credentials

Field Description

Secret Key

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

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.

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

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.

Additional Gateway Information

Credit Card Reference Transactions

Zuora supports Stripe tokens. Tokens are used for credit card reference transactions in Zuora. A reference transaction is simply a representation of a credit card payment method without having sensitive payment method information like the credit card number stored in Zuora. Note that the token cannot be used with another gateway, which is why we recommend storing credit card information in Zuora whenever possible.

This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support

See the following topics for more information about setting up Credit Card Reference payment methods in Zuora.

The following SOAP API call can be used to create a payment method that represents a Stripe-stored credit card.

<ns1:create>
  <ns1:zObjects xsi:type="ns2:PaymentMethod">
    <ns2:AccountId></ns2:AccountId>
    <ns2:SecondTokenId></ns2:SecondTokenId>
    <ns2:TokenId></ns2:TokenId>
    <ns2:Type>CreditCardReferenceTransaction</ns2:Type>
  </ns1:zObjects>
</ns1:create> 

ACH

The bank account verification through Stripe using Plaid or Stripe.js is not supported by Zuora’s Stripe gateway integration. To ensure ACH transactions work correctly, the verification of bank accounts must be turned off by Stripe for your merchant account. See Stripe's ACH Guide for more information.

The Stripe v2 gateway integration supports ACH Tokenization. This feature enhances security with end users’ bank account details by tokenizing the information into a single-use token.

Stipe v1 does not support this feature. If you want to take advantage of this feature, you should migrate to Stripe v2. Note that if you have existing ACH payment methods created with another gateway other than Stripe, you can only migrate to Stripe v2 instead of Stripe v1.