@havenpay/react-native

React Native SDK for Havenpay payment flows.

@havenpay/react-native targets Expo and bare React Native apps that need mobile-money payment sheets, hooks, view-model helpers, foreground/deep-link recovery, and typed client-secret actions.

The SDK uses a public projectId plus a short-lived payment clientSecret created by a merchant backend. It does not accept merchant secret API keys, webhook secrets, provider credentials, provider PINs, Node built-ins, DOM-only APIs in headless paths, server SDK imports, Expo Router, or React Navigation.

Install

bun add @havenpay/react-native

npm install @havenpay/react-native

React is a peer dependency. Expo Router, React Navigation, and app UI libraries remain application choices, not SDK requirements.

Use it for

• Expo or bare React Native mobile checkout flows.
• Headless payment-sheet state and actions.
• React hooks for app-owned payment screens.
• View-model helpers for custom payment, OTP, retry, and status UI.
• App foreground and return URL recovery without persisting secrets.

Quickstart

import { initHavenpay } from '@havenpay/react-native'

const havenpay = initHavenpay({
  environment: 'test',
  projectId: 'proj_...',
  merchantDisplayName: 'Merchant name',
  requestPolicy: {
    maxReadRetries: 1,
    retryBackoffMs: 100,
    timeoutMs: 10000,
  },
})

await havenpay.initPaymentSheet({
  clientSecret: 'pi_client_secret_from_your_server',
  returnUrl: 'merchant://checkout/return',
})

const intent = await havenpay.confirmPayment({
  msisdn: '+263771234567',
})

if (intent.nextAction?.type === 'mobile_money_otp') {
  await havenpay.submitAction({
    type: 'mobile_money_otp',
    otp: '123456',
  })
}

Hooks

import {
  useHavenpay,
  useMobileMoneyOtp,
  usePaymentSheet,
} from '@havenpay/react-native/hooks'

function _CheckoutScreen() {
  const havenpay = useHavenpay({
    environment: 'test',
    projectId: 'proj_...',
  })

  const _paymentSheet = usePaymentSheet(havenpay)
  const _otp = useMobileMoneyOtp(havenpay)

  // Render with React Native core components or your app design system.
  return null
}

The hooks entrypoint imports React. The default, headless, ui, and expo entrypoints stay free of React hooks, Expo Router, and navigation dependencies so bundlers can avoid hook code when an app uses custom screens.

Recovery

The SDK can create non-secret recovery snapshots for app background/foreground interruptions and return URLs. Apps may persist those snapshots in their own app state, then reacquire a fresh/current clientSecret from the merchant backend before recovery.

import {
  parseHavenpayReturnUrl,
  recoverPaymentSession,
  shouldRecoverPaymentOnAppForeground,
} from '@havenpay/react-native/expo'

const parsed = parseHavenpayReturnUrl('merchant://checkout/return?payment_intent=pi_...')

if (parsed.ok) {
  const { clientSecret } = await fetchClientSecretFromYourServer(parsed.value.paymentIntentId)

  await recoverPaymentSession({
    clientSecret,
    snapshot: parsed.value,
  })
}

if (shouldRecoverPaymentOnAppForeground({ snapshot })) {
  // Reacquire the client secret, then retrieve payment state.
}

Return URL helpers ignore any client_secret value in links. Payment authorization must come from the backend-created client secret supplied by the app.

Entrypoints

| Entrypoint | Contents | | --- | --- | | @havenpay/react-native | Default SDK exports. | | @havenpay/react-native/headless | Headless client and recovery primitives. | | @havenpay/react-native/hooks | React hooks for app-owned screens. | | @havenpay/react-native/ui | Payment-sheet view-model helpers. | | @havenpay/react-native/expo | Expo-friendly foreground and return URL helpers. | | @havenpay/react-native/testing | Test helpers for SDK consumers. |

Security boundary

Keep this SDK on the mobile client side. It must never receive:

• Merchant secret API keys.
• Webhook signing secrets.
• Provider credentials.
• Provider PINs.
• Server-only admin tokens.
• Raw provider responses.

Your backend should create PaymentIntents, manage projects and keys, verify webhooks, configure provider accounts, and issue short-lived payment client secrets.

Package boundaries

Use @havenpay/react-native for mobile client payment flows. Use @havenpay/server only on trusted backend infrastructure. Use @havenpay/core for shared public types.

The package is intentionally UI-toolkit neutral. Render the exported state with React Native core components, Expo UI, or your own design system.