@bounceapp/react-native-paypal

React Native wrapper to bridge PayPal iOS and Android SDK, support only requestBillingAgreement for the moment

Platform Compatibility

Android Device	Android Emulator	iOS Device	iOS Simulator	Expo GO	Web
✅	✅	✅	✅	❌	❌

Documentation

API Reference.

Upgrading from 0.8.x? 1.0.0 moves to Braintree Android v5 and iOS v7 and is a breaking release. See the migration guide.

Installation

yarn add @bounceapp/react-native-paypal

This is an Expo module, so your app needs the expo package. Bare React Native apps can add it with npx install-expo-modules@latest. It requires Expo SDK 56 or later.

Requirements

	Minimum
Expo	SDK 56
iOS	16.0 (Braintree iOS v7)
Android	API 23 (Braintree Android v5)

Android return URLs

Braintree Android v5 returns from the PayPal flow through an Android App Link, so you need a domain you control serving an assetlinks.json that lists your app. Pass that URL as appLinkReturnUrl on every requestBillingAgreement call.

Give the App Link its own path, such as /paypal, and scope the intent-filter to it with a pathPrefix. Without one, the filter claims every link on the host, so if you use your main domain, all of its web links open your app.

Two things to know about how Braintree handles the return:

• The pathPrefix only scopes which links Android sends to your app. Braintree itself matches a return on scheme and host alone, so another link on the same host that reaches the app during a flow is not a PayPal return. It settles as Canceled.
• If the App Link is not verified, Braintree falls back to the ${applicationId}.braintree scheme on its own.

The ${applicationId}.braintree scheme is still used, now as the fallback for buyers who have turned off "Open supported links". This library derives it from your application ID automatically — you only need to keep declaring it.

Bare Workflow

// android/app/src/main/AndroidManifest.xml
<activity
  android:name=".MainActivity"
  // ...
  >
  // ...
  <!-- App Link: the primary return path. -->
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
      android:scheme="https"
      android:host="your-app.example.com"
      android:pathPrefix="/paypal" />
  </intent-filter>
  <!-- Deep link: the fallback return path. -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="${applicationId}.braintree" />
  </intent-filter>
</activity>

Expo

Add the config plugin with the same URL you pass as appLinkReturnUrl:

// app.json
{
  "expo": {
    "plugins": [
      [
        "@bounceapp/react-native-paypal",
        { "appLinkReturnUrl": "https://your-app.example.com/paypal" }
      ]
    ]
  }
}

On prebuild it adds both intent-filters to your main activity: the App Link, scoped to the URL's path with a pathPrefix, and the .braintree fallback scheme, derived from android.package exactly as the library derives it at runtime. If you declared either filter yourself under expo.android.intentFilters, remove it.

Usage example

// App.tsx
import { useState } from "react"
import { Button } from "react-native"
import { requestBillingAgreement } from "@bounceapp/react-native-paypal"

export default function App() {
  const [loading, setLoading] = useState(false)

  const onPress = async () => {
    setLoading(true)
    const res = await requestBillingAgreement({
      clientToken: "CLIENT_TOKEN",
      // Android only: your verified App Link. Ignored on iOS.
      appLinkReturnUrl: "https://your-app.example.com/paypal",
    })

    setLoading(false)

    if (res.error) {
      console.error(res.error)
      return
    }
  }

  return <Button title="Pay with PayPal" onPress={onPress} disabled={loading} />
}

Every expected outcome resolves: a nonce in payload, or an error whose code is Canceled or Failed. The promise rejects only on a programming error, such as an option of the wrong type, so there is no need for a try/catch around the call in normal use.

👏 Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

The source code is made available under the MIT license. Some of the dependencies can be licensed differently, with the BSD license, for example.