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 | |
|---|---|---|
| Supported payment methods | Credit Card/Gift Card/Prepaid Card | Credit Card Reference Transaction |
| Supported payment operations |
|
|
| 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 |
|
https://payments.braintree-api.com/graphql |
| 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:
|
| 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. |
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:
- Enforce the 3DS2 authentication challenge if possible by selecting the 3DS2 Challenge Requested configuration field on the gateway setting page for your Braintree instance. See Configuration fields for more information.
- Implement a Payment Page to support one-time payment flow. See Implement Payment Pages 2.0 to support one-time payment flows for more information.
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 |
Description |
|---|---|---|---|
|
deviceData |
gatewayOptions.deviceData |
param_gwOptions_deviceData |
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 |
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_TaxSum | transaction.tax.taxAmount |
| gwOptions_TaxExempt | transaction.tax.taxExempt |
| 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 |
Limitation
- 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.