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

Stripe v2's support for SEPA is an Early Adopter feature. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available.

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

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

Support for Stored Credential Transactions

This feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available.

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

Configure the Stripe Payment Gateway

  1. Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway. The gateway list is displayed.
  2. Scroll down to the bottom of the gateway list and 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.

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

This feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available.

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.

Testing Your 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.

Additional Gateway Information

Credit Card Reference Transactions

This feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available.

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.

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.

ACH with Stripe requires that a customer object and a bank account object exist for each customer account. If either does not exist, Zuora will generate one on your behalf and store it as representative of your ACH account details for future use.

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.

Payment/Refund status for Stripe v2

When processing a payment or refund through an asynchronous payment method such as bank transfer and ACH, the status "Processed" in Zuora indicates that the payment or refund processing request has been successfully submitted to the Stripe v2 gateway. To get to know the final status of the payment or refund, you need to integrate the Stripe Webhook service.

Known Issue and Workaround

When creating a payment method, if the following error message is returned from Stripe, log in to the Stripe dashboard and enable Handle card information directly.

{ "error":
    {
        "message": "Sending credit card numbers directly to the Stripe API is generally unsafe. We suggest you use test tokens that map to the test card you are using, see https://stripe.com/docs/testing.",
        "type": "invalid_request_error"
    }
} 

Because both Zuora and Stripe are PCI compliant, there is no security issue if Handle card information directly is enabled.