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
    • Visa
    • Mastercard
    • American Express
    • Discover
    • JCB
    • Diners Club
  • Credit Card Reference Transaction
  • ACH
  • BACS
  • SEPA
  • PAD
  • Apple Pay
  • Google Pay
  • Credit Card/Prepaid Card/Gift Card
    • Visa
    • Mastercard
    • American Express
    • Discover
    • JCB
    • Diners Club
  • 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 Batch Gateway Reconciliation No No
Support Real-Time Reconciliation Yes No
Support Payment Method Updater No No
Support non-referenced refunds

Yes

Supported for Credit Card payment methods

No
Support ACH Tokenization Yes No
Support Stripe Radar 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 sections provide additional information for each supported payment method type.

For more information about the supported currencies, see Supported currencies by gateways.

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

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. 

For Credit Card Reference Transaction (CC Ref) payment methods created through the UI or API operation, only existing Stripe tokens are supported. Creating tokens in Zuora is not supported. For CC Ref payment methods created on Stripe v2 through the hosted payment page, tokens will be generated by Zuora.

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 generated from the Credit Card payment method is acceptable:
    • Stripe Payment Method ID starting with "pm_". Note that only Stripe v2 supports this type of ID.
    • 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

ACH tokenization

To create tokenized ACH payment methods, use one of the following approaches. The mappings between token fields are as follows.

Stripe Field Zuora Field
Stripe Payment Method Id (pm_xxxxxxxx) tokens > tokenId
Stripe Customer Id (cus_xxxxxxxx) tokens > secondTokenId

Approaches to creating tokenized ACH payment methods:

Approach Description Example
Create a payment method API operation

 

Pass in existing tokens and masked account number

Make sure the payment method is active and the account is valid, and then pass in the following information:

  • Pass in Stripe Payment Method Id through tokens > tokenId
  • Pass in Stripe Customer Id through tokens > secondTokenId
  • Pass in the masked account number through bankAccountMaskNumber

To enable this option, submit a request at Zuora Global Support.

{
  "accountKey": "8a90d6128d45df2b018d4b90681c05x0",
  "bankABACode": "999999999",
  "bankAccountName": "TestName",
  "bankAccountType": "Checking",
  "bankName": "TestBank",
  "type": "ACH",
  "bankAccountMaskNumber": "****2345",
  "tokens": {
    "gatewayType": "Stripe",
    "tokenId": "testTokenId",
    "secondTokenId": "testSecondTokenId"
  }
}
UI Tokens will be automatically generated and stored for the payment method.  
Hosted payment page Tokens will be automatically generated and stored for the payment method.  

For tokenized payment methods, you must validate them in Zuora so that payments made with these payment methods are successful. To validate tokenized payment methods, enable the following settings on the gateway instance configuration page:

  • Verify new payment method
  • Verify updated payment method

ACH account verification

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 a representative of your ACH account details for future use.

The bank account verification through Stripe using 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. If the payment method was created before turning off the ACH account verification, the payment fails with the "cannot be used because it is not verified" error. You must create an ACH payment method to process the payment after turning off the verification. See Stripe's ACH Guide for more information.

ACH payment method verification is supported through the ValidiFi account validation service. See Enable the support for ValidiFi account validation for ACH for details.

Direct Debit UK (BACS)

To create tokenized BACS payment methods, use one of the following approaches. The mappings between token fields are as follows:

Stripe Field Zuora Field
Stripe Customer Id (cus_xxxxxxxx) tokens > tokenId
Stripe Payment Method Id (pm_xxxxxxxx) tokens > secondTokenId

Approaches to creating tokenized BACS payment methods:

Approach Description Example
Create a payment method API operation

 

Option 1: Pass in existing tokens and masked account number

Pass in Stripe Customer Id through tokens > tokenId.

Pass in Stripe Payment Method Id  through tokens > secondTokenId.

Pass in the masked account number through accountMaskNumber

Tokenizing BACS payment methods through this option is generally available in Sandbox environments. To enable it in Production environments, submit a request at Zuora Global Support.
{
   "accountKey": "402881868ab1b937018ab2314b91234a",
   "bankCode": "10880",
   "accountHolderInfo": {
            …
    },
    "type": "Bacs",
    "accountMaskNumber": "****2345",
    "tokens": {
        "gatewayType": "Stripe",
        "tokenId": "testTokenId",
        "secondTokenId": "testSecondTokenId"
    }
}

Option 2: Pass in the account number and the fields that are required by Stripe for validating the tokenized payment method

Pass in the account number through accountNumber.

Pass in the following Gateway Options fields:

  • ipAddress
  • UserAgent

Tokens will be generated and stored for the payment method.

{
    "accountNumber": "00012345",
    "accountKey": "402881868ab1b937018ab2314b91234a",
    "bankCode": "10880",
    "accountHolderInfo": {
            …
    },
    "type": "Bacs",
    "gatewayOptions": {
         "ipAddress": "3:3:3:3:3:3:2:1",
         "UserAgent": "Test123456"
    }
}
UI Tokens will be automatically generated and stored for the payment method.  
Hosted payment page Tokens will be automatically generated and stored for the payment method.  

For tokenized payment methods, you must validate them in Zuora so that payments made with these payment methods are successful. To validate tokenized payment methods, enable the following settings on the gateway instance configuration page:

  • Verify new payment method
  • Verify updated payment method

Single Euro Payments Area (SEPA)

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

When creating payment methods, ensure that all required fields are included:

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

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

Canadian Pre-Authorized Debit (PAD)

Zuora only supports the creation of PAD on Stripe v2 through Hosted Payment Pages. Ensure that all required fields are included. See Payment Pages 2.0 form fields for more information.

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.

Apple Pay

Stripe v2 provides support for Apple Pay. The following credit card types are supported by this gateway integration to create Apple Pay payment methods and process Apple Pay transactions:

  • VISA
  • Mastercard
  • American Express
  • Discover
  • JCB

For more information about setting up Apple Pay on Stripe v2, see Set up Apple Pay.

Google Pay

Stripe v2 provides support for Google Pay. You can add Google Pay to your checkout flow by integrating with a JavaScript SDK provided by Zuora. For more information, see See Set up Google Pay with Zuora JavaScript SDK.

Mandate creation for payment methods

When creating one of the following payment methods, the mandate information listed in the following table 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.

  • Credit Cards
  • SEPA
  • PAD
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 Processing

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.

While creating recurring off-session payments without 3DS2, Zuora does not create customer accounts on the Stripe side. Zuora creates customer accounts on the Stripe side for the following transactions:

  • One-time on-session payments
  • Recurring off-session payments with 3DS2

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

The Delayed Capture feature allows you to authorize the availability of funds for a transaction but delay the capture of funds until a later time. The Stripe v2 gateway integrations support Delayed Capture for Credit Card payment methods. For how to use the Delayed Capture feature, see Payment Authorization in Zuora API Reference.

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 and the sharing NTI feature. For details, see Support for stored credential transactions overview.

Support for Stripe Radar

If Stripe Radar is enabled in both Stripe and Zuora, Zuora uses Stripe client-side SDK to collect the Radar Session ID and pass it to Stripe. Credit Card and Credit Card Reference payment transactions sent to Stripe from Zuora will be assessed for fraudulent activity by Stripe Radar. To enable the support for Stripe Radar in Zuora, submit a ticket at Zuora Global Support.

You can use Additional Metadata and Gateway Options fields to build your custom Stripe Radar rules. To disable the support for Stripe Radar in Zuora, see Set up and configure a Stripe payment gateway instance.

Support for Real-Time Reconciliation

Stripe v2 supports the Real-Time Reconciliation feature. With this feature enabled, the payment gateway can submit notifications to Zuora for various event types on gateway objects, and the corresponding records can be automatically updated in real time.

  1. For information about how to enable Real-Time Reconciliation and the limitation, see Real-Time Reconciliation.

  2. For information about the supported events for Stripe v2 and the corresponding actions from Zuora, See Real-Time Reconciliation events for Stripe v2.

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.

All Gateway Options fields are string fields.

Gateway Options field Description
RadarSessionId

For Credit Card and Credit Card Reference transactions, use this field to pass in the Radar session ID. This Gateway Options field can only be used through the the gatewayOptions field of the Create a payment API operation.

Here is an example:

"gatewayOptions": {
    "RadarSessionId": "rse_1N7fvKSDx60UgxZnDB5Hb4v5" 
}
ipAdddress Use this field to pass in your customer’s IP address. This Gateway Options field can only be used in the Create a payment method API operation when creating tokenized BACS payment methods on Stripe. For more information, see Direct Debit UK (BACS).
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 Manage stored credential profiles.

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.