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 |
|
| Supported payment operations |
|
|
| Support 3D Secure 2.0 | Yes | Yes |
| Support Delayed Capture | No | Yes |
| Support Level 2 and Level 3 card data | No | Yes |
| Support stored credential transactions | Yes | Yes |
| 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 inquiry call for retrying a transaction request | No | Yes. See Electronic payment processing for details. |
| 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 |
|
See Set up payment methods on Braintree v2.0 for more information.
Supported payment flows
For the following payment methods, you can configure and integrate a Payment Page 2.0 to support processing payment flows:
- Credit Card on both versions of the payment gateway integrations
- ACH on Braintree v2.0
For the following payment methods, you can implement JavaScript SDK integration to support processing payment flows:
- Apple Pay on Braintree v2.0
- Google Pay on Braintree v2.0
- PayPal on Braintree v2.0
The following payment flows are supported:
- Create and save a payment method.
- Process a one-time payment without saving the payment method.
- Process the first payment and save the payment method for subsequent recurring payments.
For more information, see the following articles:
Support for 3D Secure 2.0
Both Braintree and Braintree v2.0 gateway integrations provide support for 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 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 Braintree v2.0 payment gateway integration supports Delayed Capture for all the supported payment methods, which involves the use of the following API operations:
- Create authorization
- Create a payment to capture the payment or Cancel authorization
Zuora also supports capturing authorizations that were generated externally by using Zuora's Create authorization API operation.
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
Both Braintree and Braintree v2.0 gateway integrations include support for the Stored Credential Transactions framework.
The Braintree gateway integration also supports the sharing NTI feature, while the Braintree v2.0 gateway integration does not support it.
For details, see Support for stored credential transactions overview.
Supported Gateway Options fields
Through both versions of 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
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.