Skip to main content

Overview of Stripe payment gateway integration

Zuora

Overview of Stripe payment gateway integration

Zuora supports the following Stripe gateway integration versions. This article describes supported features and limitations for these versions.

  • Stripe v2
  • Stripe v1

Supported features

The following table provides a quick reference for the supported features. For details about each feature, see the later sections in this article.

Feature Stripe v2 Stripe v1
Supported payment methods
  • Credit Card/Prepaid Card/Gift Card
  • Credit Card Reference Transaction
  • ACH
  • BACS
  • SEPA
  • PAD
  • Credit Card/Prepaid Card/Gift Card
  • Credit Card Reference Transaction
  • ACH
Support 3D Secure 2.0 Yes No
Support Delayed Capture Yes No
Support Level 2 and Level 3 card data Yes No
Support stored credential transactions Yes No
Support Gateway Options fields Yes No
Gateway provider’s API version 2019-05-16 2015-02-18
Stripe production endpoint used for Zuora gateway integration service

https://api.stripe.com/v1/setup_intents

https://api.stripe.com/v1/payment_intents

https://api.stripe.com/v1/refunds

https://api.stripe.com/v1/customers

https://api.stripe.com/v1/customers

https://api.stripe.com/v1/charges

https://api.stripe.com/v1/customers/<customer_id>/sources

https://api.stripe.com/v1/charges/<ReferenceId>/refunds

Support Gateway Reconciliation No No
Support Payment Method Updater No No
Support non-referenced refunds Yes No
Support ACH Tokenization Yes No
Support one-time payment flow through Payment Pages 2.0 Yes No
Support idempotency for retrying a transaction request Yes. See Electronic payment processing for details. No
Support for MOTO transactions Yes No

Supported payment methods

The following table lists the supported payment methods for each Stripe integration version:

  Stripe v2 Stripe v1
Supported payment methods
  • Credit Card/Prepaid Card/Gift Card
    • Visa
    • Mastercard
    • American Express
    • Discover
    • JCB
    • Diners Club
  • Credit Card Reference Transactions
  • ACH
  • BACS
  • SEPA
  • PAD
  • Credit Card/Prepaid Card/Gift Card
    • Visa
    • Mastercard
    • American Express
    • Discover
    • JCB
    • Diners Club
  • Credit Card Reference Transactions
  • ACH

For more information about setting up payment methods in Zuora, see Define and set up payment methods.

The following sections provide additional information for each payment method.

Credit Card Reference Transaction

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. Zuora supports Stripe tokens. Note that the token cannot be used with another gateway, which is why we recommend storing credit card information in Zuora whenever possible. Currently, only existing Stripe tokens are supported as a Credit Card Reference Transaction payment method type. Creating tokens in Zuora is not supported.

Complete the following prerequisites for processing credit card reference transactions:

  • Enable the Credit Card Reference Transaction payment method in Zuora:
    1. Click your username on the upper right.
    2. Navigate to Settings > Payments > Payment Method. The Customize Payment Methods page opens.
    3. Click Edit, and select CC Reference Transaction.
  • Contact Zuora Global Support to enable the Payment Tokenization feature for your tenant.

When setting up a Credit Card Reference Transaction payment method on Stripe, both of the following fields are required:

  • Token ID. Any of the following values are acceptable:
    • Stripe Payment Method ID starting with "pm_"
    • Stripe Bank Account ID starting with "ba_"
    • Stripe Card ID starting with "card_"
    • Stripe Source ID starting with "src_"
  • Second Token ID. The value must be the Stripe Customer ID.

For more information about the Stripe token object, see Stripe documentation.

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.

Zuora only supports the creation of ACH payment methods with Stripe through either Hosted Payment Pages or API.

Bank Transfer

Stripe v2 supports the following types of Bank Transfer payment methods:

  • Direct Debit UK (BACS)

    Zuora supports the creation of BACS on Stripe v2 through either Hosted Payment Pages or API.

  • Single Euro Payments Area (SEPA)

    Zuora supports the creation of SEPA on Stripe v2 through either Hosted Payment Pages or API.

  • Canadian Pre-Authorized Debit (PAD)

    Zuora only supports the creation of PAD on Stripe v2 through Hosted Payment Pages.

When creating these Bank Transfer payment methods through the API, ensure that all required fields are included in the request. For details about the required fields for each payment method type, see API Reference.

When creating these Bank Transfer payment methods through Hosted Payment Pages, ensure that the required fields described in Payment Pages 2.0 form fields are marked as the required fields on the payment page form.

Additional information for SEPA

The following table describes the mapping relationship of major fields of the SEPA payment method between Zuora and Stripe:

Zuora field Stripe field
MandateId Mandate ID
TokenId Customer ID
SecondTokenId Payment Method ID

Additional information for PAD

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

If Stripe’s verification is not disabled, you must build a custom process to handle those verifications.

Mandate creation for payment methods

Stripe v2 supports mandate creation for the following payment methods:

  • Credit Cards
  • BACS
  • SEPA
  • PAD

When creating one of these payment methods, the following mandate information is required by the gateway. Passing in the existing mandate ID is not supported for now. See the below table on how to pass the information to the gateway to generate a mandate.

Mandate information required by the gateway Pass the fields to the gateway through Payment Pages 2.0 Pass the fields to the gateway through API
The IP address from which the mandate was accepted by the customer

These 3 fields will be generated and passed to the gateway by Zuora.

 

You need to pass in this information by using the ipAddress field in the request body of the Create a payment method API operation.
The user agent of the browser from which the mandate was accepted by the customer You need to pass in this information by using the gatewayOptions field in the request body of the Create a payment method API operation. Use UserAgent as the key name.
The time at which the customer accepted the mandate This field will be generated and passed to the gateway by Zuora.

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.

Support for 3D Secure 2.0

See Enable 3DS2 for Stripe gateway integration and Zuora’s implementation of 3D Secure 2.0 for more information.

Support for Delayed Capture

You can use the Delayed Capture feature to authorize available funds for a transaction but delay the capture of funds until a later time. Zuora's Stripe v2 gateway integrations support Delayed Capture for credit card payment methods. You can use the Create authorization API operation to authorize a payment amount before capturing the payment. Subsequently, you can use Create a payment to fully or partially capture the authorized amount, or use Cancel authorization to cancel the authorization. 

Note that you can perform only one capture on an authorized payment. If you partially capture a payment, you cannot perform another capture.

Support for Level 2 and Level 3 card data

Stripe v2 supports processing Level 2 and Level 3 credit card data. For more information, see the following articles:

Support for stored credential profiles

Stripe v2 includes support for the Stored Credential Transactions framework. For details about the supported payment methods, see Support for stored credential transactions overview.

Supported Gateway Options fields

You can submit additional information to the Stripe gateway by using the Gateway Options fields. The Stripe v2 gateway integration supports the following Gateway Options fields.

Gateway Options field Description
UserAgent

Use this field to pass in the user agent of the browser from which the mandate of a payment method was accepted by the customer. This Gateway Options field can only be used in the Create a payment method API operation. For more information about how to use this field, see Mandate creation for payment methods.

CardMandateReference

CardMandateDescription

CardMandateAmountType

CardMandateAmount

CardMandateStartDate

CardMandateEndDate

CardMandateInterval

CardMandateIntervalCount

Use these fields to pass in the information required for generating the e-mandate for recurring payments in India. These Gateway Options fields can only be used in Payment Pages 2.0. For more information about how to use these fields, see Implement Payment Pages 2.0 to support processing payments in India.

Support for MOTO transactions

Credit card payment transactions through Stripe v2 can be processed as Mail Order Telephone Order (MOTO) payment transactions. When creating a payment through the UI or API operation, you can specify the following field with MOTO. The MOTO transaction indicator will be included in the request to the gateway and a recurring stored credential profile will be created for the payment method used to process the payment. The network transaction ID (NTI) will be returned in the authorization response.

  Field Value
UI for creating a payment Transaction Source Merchant Initiated MOTO Transaction
Create a payment API operation mitTransactionSource M_MOTO

You can also use MOTO transactions to create stored credential profiles when creating credit card payment methods through UI or processing recurring card payment transactions. For details, see the following articles:

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.