Skip to content

README.md

Latest commit

 

History

History
191 lines (135 loc) · 9.45 KB

README.md

File metadata and controls

191 lines (135 loc) · 9.45 KB
Raw

react-native-expo-braintree

A high-performance, native implementation of the Braintree SDK for React Native and Expo, powered by Nitro Modules.

Note

This package is the successor to react-native-paypal-reborn. The name change reflects the addition of first-class Expo support. All future updates and features will be released under react-native-expo-braintree.

Warning

Version 4.0.0 is in Alpha Please note that version 4.0.0 is currently in an alpha state. If you run into any issues, bugs, or unexpected behavior, feel free to create an issue on the GitHub repository.

NPM Version MIT License Platform support

Warning

Version Deprecation Notice Starting with the release of version 4.x, all support for version 3.x has been discontinued. There will be no further features, bug fixes, or compatibility patches released for the 3.x line. It is highly recommended to upgrade to version 4.x (which features a full native rewrite powered by high-performance JSI Nitro Modules).

Note

Legacy Documentation (v3.x) If you are still using the legacy version 3.x of this library, you can refer to the following guides:

Key Features

  • Nitro Modules Architecture: Uses direct JSI bindings bypassing the legacy React Native bridge for zero-serialization overhead and near-instantaneous call execution.
  • Full Payment Method Coverage: Support for 7 Braintree payment types.
  • Expo Config Plugin: Out-of-the-box support for Expo SDK 53, 54, and 55 with minimal configuration.

Supported Payment Methods

Method Android iOS Details
PayPal One-Time Payment ✅ ✅ Standard checkout flow
PayPal Billing Agreement ✅ ✅ Vaulting checkout flow
Card Tokenization ✅ ✅ Direct credit card input tokenization
3D Secure ✅ ✅ Bank risk check verification
Venmo Partially Supported (might be some web switch problems) Partially Supported (might be some web switch problems) Venmo App / Web authentication switch
Google Pay ✅ N/A Google Pay sheets integration
Data Collector ✅ ✅ Advanced fraud tracking / device data profiling

Compatibility Matrix

Native SDK Versions

Package Version Braintree Android Braintree iOS Min Android SDK Min iOS
4.0.0 v5.19.0 v7.5.0 23 15.1
3.5.0 v5.19.0 v7.5.0 23 15.1
3.4.0 v5.19.0 v6.41.0 23 15.1
3.3.0 v5.19.0 v6.41.0 23 15.1
3.2.0 - 3.2.2 v5.19.0 v6.41.0 23 15.1
3.1.0 v5.9.x v6.31.0 23 14.0
3.0.1 - 3.0.5 v5.2.x v6.23.3 23 14.0
2.2.0 - 2.4.0 v4.41.x v6.17.0 21 14.0

Expo SDK Support

Package Version Supported Expo SDK
4.0.0 53, 54, 55
3.2.1+ 53, 54
3.0.3 - 3.1.0 50, 51, 52
3.0.1 - 3.0.2 50, 51
2.5.0 50, 51, 52
2.2.0 - 2.4.0 50, 51

Feature History

Package Version Release Key Features & Changes
4.0.0 Core native rewrite in Kotlin & Swift powered by Margelo's JSI Nitro Modules (high performance, sync/async invocation, zero bridge-overhead)
3.5.0 Braintree iOS SDK v7 update
3.4.0 Google Pay Feature Added
3.3.0 3D Secure Feature Added

Installation

npm install react-native-expo-braintree react-native-nitro-modules

Note

react-native-nitro-modules must be installed as a peer dependency alongside this package as it provides the core JSI binding framework.

Integration

Please refer to the following guides to configure Braintree inside your project structure:

Usage

For complete API listings, TypeScript structures, enums, and quick examples, check the USAGE_4.X.md guide.

Demos

iOS Android

Troubleshooting Guide

1. Required Setup: Android App Links

Braintree Android SDK v5 requires the configuration of App Links rather than legacy custom deep links.

  • Official Setup Instruction: Refer to the Braintree App Links setup guide.
  • Server Configuration: Your web domain must host a valid association configuration file at https://your-domain.com/.well-known/assetlinks.json. An example configuration is available at the Braintree Example assetlinks.json.
  • Validation: Verify that the package association has been verified on the target device: 
    adb -d shell pm get-app-links <YOUR_PACKAGE_NAME>
    Expected output for verified host: your-braintree-domain.com: verified.

2. Common Integration Issues

A. Missing Fallback Scheme (Android)

  • Symptom: TOKENIZE_VAULT_PAYMENT_ERROR is returned during requestBillingAgreement calls on Android devices.
  • Fix: Configure addFallbackUrlScheme in the Expo plugin properties: 
    "plugins": [
  ["react-native-expo-braintree", {
    "host": "your-domain.com",
    "pathPrefix": "/payments",
    "addFallbackUrlScheme": "true"
  }]
]
    Note: Ensure the fallback scheme ends with .braintree (e.g. com.your.app.braintree).

B. 3DSecure Layout Crash (Android 14+)

  • Symptom: Window layout issues or crashes during the 3D Secure modal trigger on Android 14.
  • Fix: Add the following dependency to build.gradle: 
    dependencies {
    api "androidx.activity:activity:1.9.3"
}

Support

If you continue to experience issues after verifying the App Link state and the Fallback Scheme, please create an Issue on the GitHub repository: GitHub Issues

Special Thanks

  • iacop0 — For introducing Venmo Integration and Android Version Bump.

Roadmap

  • Complete native module rewrite in Kotlin & Swift powered by JSI Nitro Modules (v4.0.0)
  • Venmo Integration
  • 3D-Secure
  • Google Pay
  • Apple Pay (TBD)

License

This project is licensed under the MIT License - see the LICENSE file for details.