Add giving to a React Native app

The @thefaithapp/giving-react-native package renders general and campaign giving inside a React Native or Expo app. It uses the member session from @thefaithapp/auth-react-native, presents the church’s active payment provider, and waits for TheFaithApp to confirm the payment. The package includes:

general giving with funds, currency, frequency, memo, and fee coverage
campaign giving with configured donor form fields
Stripe PaymentSheet
hosted PayPal and Flutterwave checkout
checkout cancellation and expiry handling
headless checkout and custom payment-handler support

TheFaithApp creates and verifies each checkout and processes provider webhooks. Do not add payment-provider secret keys or webhook secrets to your mobile app.

Before you begin

You need:

an Expo SDK 57 or compatible React Native app
@thefaithapp/auth-react-native configured with a client API key
a signed-in TheFaithApp member
an active payment provider configured for the church
a native development or standalone build

Follow the React Native SDK Quickstart first if member sign-in is not working yet.

Install the packages

Install the auth and giving SDKs:

npm install @thefaithapp/auth-react-native @thefaithapp/giving-react-native

Add the native payment dependencies with Expo-compatible versions:

npx expo install @stripe/stripe-react-native react-native-webview
npx expo install expo-application expo-crypto expo-secure-store expo-web-browser

Configure the native plugins

Add an application scheme, the auth plugin, and the Stripe plugin to app.json:

{
  "expo": {
    "scheme": "your-church",
    "plugins": [
      "@thefaithapp/auth-react-native",
      [
        "@stripe/stripe-react-native",
        {
          "merchantIdentifier": "merchant.com.example.church",
          "enableGooglePay": false
        }
      ],
      "expo-secure-store",
      "expo-web-browser"
    ],
    "ios": {
      "bundleIdentifier": "com.example.church"
    },
    "android": {
      "package": "com.example.church"
    }
  }
}

Rebuild the native application after changing plugins:

npx expo run:ios
# or
npx expo run:android

Stripe PaymentSheet cannot run in Expo Go.

Create the authenticated giving client

Reuse the auth instance that signs the member in:

import { TheFaithAppAuth } from '@thefaithapp/auth-react-native'
import {
  TheFaithAppGiving,
  createStripeGivingPaymentHandler,
} from '@thefaithapp/giving-react-native'

const auth = new TheFaithAppAuth({
  apiKey: process.env.EXPO_PUBLIC_THEFAITHAPP_API_KEY!,
})

const giving = new TheFaithAppGiving({
  auth,
  paymentHandlers: [
    createStripeGivingPaymentHandler({
      urlScheme: 'your-church',
      returnUrl: 'your-church://stripe-redirect',
    }),
  ],
})

The Stripe override adds the return URL used by redirect and 3DS flows. Its provider ID replaces the built-in Stripe handler while PayPal and Flutterwave continue to use their built-in handlers.Before showing protected giving:

const session = (await auth.currentSession()) ?? (await auth.signIn())
console.log(`Giving as ${session.member.name}`)

The giving client does not accept a member ID or church/client ID. The authenticated session supplies that identity on every request.

Render general giving

Add the built-in general giving view to a screen:

import { GeneralGivingView } from '@thefaithapp/giving-react-native'

export function GivingScreen() {
  return (
    <GeneralGivingView
      giving={giving}
      onCompleted={(result) => {
        // result.state is succeeded, pending, failed, or cancelled.
      }}
      onError={(error) => {
        // Show a safe message without logging checkout data.
      }}
    />
  )
}

The view loads the church’s giving settings and funds. It shows only the currencies, recurrence options, memo, and fee coverage allowed by that configuration.

Render campaign giving

Your app chooses the campaign, then passes its numeric ID to the view:

import { CampaignGivingView } from '@thefaithapp/giving-react-native'

export function CampaignScreen({
  campaignId,
}: {
  campaignId: number
}) {
  return (
    <CampaignGivingView
      campaignId={campaignId}
      giving={giving}
      onCompleted={(result) => {
        // Handle succeeded, pending, failed, or cancelled.
      }}
    />
  )
}

If the campaign has donor fields, the package renders and validates its text, multiline text, number, email, telephone, select, radio, checkbox, and date fields.Campaign discovery and selection belong to your app. The package begins with the campaign ID you provide.

Payment-provider behavior

The package uses the church’s active/default provider. An app does not choose between Stripe, PayPal, and Flutterwave for an individual gift.

Provider	Experience
Stripe	Native PaymentSheet
PayPal	Hosted approval in an in-app WebView
Flutterwave	Hosted checkout in an in-app WebView

The result from a native sheet or WebView is not treated as proof of payment. The SDK checks TheFaithApp’s webhook-backed status before reporting the final state. A pending result means the provider or webhook is still processing.

Campaign fields

The built-in campaign view loads the campaign definition and submits its form responses with the authenticated checkout. Required fields are validated before the payment experience opens. Both giving views accept partial strings overrides, contentContainerStyle, allowRecurring, and showMemo.

Headless checkout

The rendered views are optional. A custom form can create an authenticated checkout and render the shared payment host:

const checkout = await giving.createGeneralCheckout({
  allocations: [{ amount: 25, fundId: 4 }],
  currency: 'USD',
  frequency: 'one_time',
})

<GivingPaymentHandlerHost
  giving={giving}
  checkout={checkout}
  onComplete={setResult}
  onError={setError}
/>

For a campaign, call createCampaignCheckout(campaignId, request) and include the campaign’s configured values in request.formFields. Keep the host mounted until the provider completes. If your custom UI dismisses an unrendered checkout, report it:

await giving.abandonCheckout(checkout)

Add another payment provider

import type {
  GivingPaymentHandler,
  GivingPaymentHandlerProps,
} from '@thefaithapp/giving-react-native'

function ChurchPay({
  checkout,
  onComplete,
  onError,
}: GivingPaymentHandlerProps) {
  // Present the provider UI and confirm authoritative checkout status.
  return null
}

const churchPayHandler: GivingPaymentHandler = {
  provider: 'church-pay',
  Component: ChurchPay,
}

const giving = new TheFaithAppGiving({
  auth,
  paymentHandlers: [churchPayHandler],
})

A handler receives only one checkout’s ephemeral session and narrow completion capabilities. It does not receive the auth client, client API key, bearer token, member ID, or church ID. Never persist or log checkout provider data. A custom handler must complete with the same donation ID and provider it received.

Cancellation and cleanup

Closing a payment experience triggers a best-effort checkout abandonment request. If the device is offline or the app terminates before that request arrives, TheFaithApp expires the checkout on the server. A late valid webhook still has a short grace period so a completed payment is not incorrectly cancelled.

Troubleshooting

Problem	What to check
Giving says it is unavailable	Confirm the church has an active/default payment provider and supported giving configuration.
The member is not authenticated	Restore or create the auth session before rendering the giving view.
Stripe does not open	Use a native development build, rebuild after adding the plugin, and confirm the Stripe return scheme.
The app does not return after 3DS	Confirm `returnUrl` uses the scheme registered in `app.json`.
A campaign cannot be loaded	Confirm the campaign ID belongs to the signed-in member’s church and the campaign is available.
A required campaign field is missing	Render the campaign returned by the package instead of maintaining a separate field definition.
A payment remains pending	Keep the status message visible; TheFaithApp updates the donation when the provider webhook arrives.

Get Started

Endpoints

React Native Giving SDK

Add giving to a React Native app

Before you begin

Payment-provider behavior

Campaign fields

Headless checkout

Add another payment provider

Cancellation and cleanup

Troubleshooting

Package resources

​Add giving to a React Native app

​Before you begin

​Payment-provider behavior

​Campaign fields

​Headless checkout

​Add another payment provider

​Cancellation and cleanup

​Troubleshooting

​Package resources

Add giving to a React Native app

Before you begin

Payment-provider behavior

Campaign fields

Headless checkout

Add another payment provider

Cancellation and cleanup

Troubleshooting

Package resources