Skip to main content

Overview of payment gateway integration for Braintree


Overview of payment gateway integration for Braintree

Zuora provides the following versions of payment gateway integration for Braintree:

  • Braintree
  • Braintree v2.0

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.

  Braintree Braintree v2.0
Development status Active Active
Supported payment methods Credit Card/Gift Card/Prepaid Card Credit Card Reference Transaction
Supported payment operations
  • Payment method validation
  • Payment
  • Payment cancel
  • Referenced refund
Support 3D Secure 2.0 Yes No
Support Delayed Capture No No
Support Level 2 and Level 3 card data No Yes
Support stored credential transactions Yes No
Support Gateway Options fields Yes Yes
Gateway provider’s API version version 2.81.0, Braintree Java JAR Braintree GraphQL API
Braintree production endpoints used for Zuora gateway integration service
Support Gateway Reconciliation No No
Support Payment Method Updater No No
Support one-time payment flow through Payment Pages 2.0 Yes No
Support idempotency for retrying a transaction request No No
Support Asynchronous Payment Statuses Yes No

Supported payment methods

Gateway integration version Payment method type
Braintree Credit Card/Gift Card/Prepaid Card, including:
  • Visa
  • MasterCard
  • Discover
  • American Express
  • JCB
  • Diners Club
Braintree v2.0

Credit Card Reference Transaction (CC Ref)

Note that you can only create CC Ref payment methods on Braintree v2.0 by using the REST API operation.

To create a CC Ref payment method, a multi-use payment method ID is required. See the following Braintree documentation for how to get a multi-use payment method ID.

Support for 3D Secure 2.0

Zuora's Braintree gateway integration provides support for 3DS2 through the embedded iFrame of Payment Pages 2.0. The Braintree v2.0 payment gateway integration does not support 3DS2.

To enable 3DS2, see Enable 3DS2 for Braintree gateway integration and Zuora’s implementation of 3D Secure 2.0 for more information.

After 3DS2 is enabled in the Payment Pages settings, the following features are supported:

The "Best practices" section in Zuora’s implementation of 3D Secure 2.0 also provides best practices for reducing the possibility of failed transactions due to 3DS2 authentication errors.

Support for Level 2 and Level 3 card data processing

The Braintree v2.0 payment gateway integration supports processing Level 2 and Level 3 credit card data. For more information, see the following articles:

Support for stored credential profiles

Braintree gateway includes support for the Stored Credential Transactions framework and the sharing NTI feature. The Braintree v2.0 payment gateway integration does not support the SCT framework.

For details, see Support for stored credential transactions overview.

Supported Gateway Options fields

Through the payment gateway integration for Braintree, you can submit the following additional information to the Braintree gateway by using Gateway Options fields through Payment Pages or the Create a payment REST API operation.

Gateway Options fields supported by the Braintree gateway integration

Braintree field Zuora API field

Zuora Payment Page client parameter





Type: string

The device ID, such as "{\"correlation_id\":\"9a7eff837a54329c381a339effbfcd56\"}"

You need to collect the deviceData by using Braintree dataCollector on the client side and pass the collected deviceData to Zuora through the Gateway Options field.

For more information about the deviceData field of Braintree, see Braintree Developer Docs.

Here are examples for how to specify the parameters:

Through Payment Pages 2.0:

"param_gwOptions_deviceData" : "{\"correlation_id\":\"9a7eff837a54329c381a339effbfcd56\"}"

Through the Create a payment API operation:

"gatewayOptions": {
    "deviceData": "{\"correlation_id\":\"9a7eff837a54329c381a339effbfcd56\"}"

Gateway Options fields supported by the Braintree v2.0 gateway integration

The Braintree v2.0 payment gateway integration supports passing the following Gateway Options fields through the Create a payment operation. For a detailed description of each field, see Braintree’s documentation.

Zuora Field Braintree API Field
gwOptions_InvoiceNum transaction.purchaseOrderNumber
gwOptions_DiscountAmount transaction.discountAmount
gwOptions_ShippingAmount transaction.shipping.shippingAmount
gwOptions_SoldToContactZip transaction.shipping.shipsFromPostalCode
gwOptions_SoldToContactCountry transaction.shipping.shippingAddress.countryCodeAlpha3
gwOptions_SoldToContactZip transaction.shipping.shippingAddress.postalCode
gwOptions_SoldToContactFirstName transaction.shipping.shippingAddress.firstName
gwOptions_SoldToContactLastName transaction.shipping.shippingAddress.lastName
gwOptions_SoldToContactAddress1 transaction.shipping.shippingAddress.streetAddress
gwOptions_SoldToContactAddress2 transaction.shipping.shippingAddress.extendedAddress
gwOptions_SoldToContactCity transaction.shipping.shippingAddress.locality
gwOptions_SoldToContactState transaction.shipping.shippingAddress.region


  • Neither version of the payment gateway integration for Braintree supports non-referenced refunds.
  • The Braintree v2.0 integration does not support Payment Pages 2.0 for now. An external method of token generation is required.
  • The Braintree v2.0 integration does not support the creation of CC Ref payment methods through Zuora UI.
  • No Payment Method Updater service is available for the Braintree or Braintree v2.0 payment gateway integration in Zuora. You can use Braintree's Account Updater service to update the credit card information on the Braintree side. This service operates independently of Zuora. Therefore, you must manually configure the Account Updater service in Braintree instead of in Zuora.