Payment Widget

The PaymentWidget component renders an embedded, inline payment form directly inside your screen, instead of opening a modal payment sheet. This approach is useful for custom checkout pages where you want full control over layout and UI.

1. Basic Usage

1.1 Install the react native sdk

npm install @juspay-tech/react-native-hyperswitch
# or
yarn add @juspay-tech/react-native-hyperswitch

1.1.1 Install Peer Dependencies

The SDK requires the following peer dependencies to be installed in your project:

yarn add react-native-inappbrowser-reborn
yarn add react-native-svg
yarn add @sentry/react-native
# or
npm install react-native-inappbrowser-reborn
npm install react-native-svg
npm install @sentry/react-native

1.2 Wrap your app with HyperProvider

To initialize Hyperswitch in a React Native application, wrap your payment screen with the HyperProvider component. The publishable key is required and must be provided to the HyperProvider during initialization.

import { HyperProvider } from "@juspay-tech/react-native-hyperswitch ";

function App() {
  return (
    <HyperProvider publishableKey="YOUR_PUBLISHABLE_KEY" profileId="YOUR_PROFILE_ID">
      // Your app code here
    </HyperProvider>
  );
}

1.3 Fetch the PaymentIntent client Secret

Send a network request to the backend endpoint created in the previous step to retrieve the clientSecret. This clientSecret returned from the endpoint is required to complete the payment.

useEffect(() => {
    fetch('https://your-server.com/create-payment-intent', { method: 'POST' })
      .then((res) => res.json())
      .then(({ clientSecret, sdkAuthorization, }) => {
        setClientSecret(clientSecret));
        setAuthorization(sdkAuthorization);
        }
}, []);

1.4 Render your Payment widget

Use the Hyperswitch PaymentWidget component to render an embedded payment form

import {PaymentWidget} from '@juspay-tech/react-native-hyperswitch';

return(
 <PaymentWidget
  widgetId="checkout-widget"
  widgetType="PAYMENT_SHEET"
  options={{ clientSecret, sdkAuthorization, appearance: { theme: 'light' } }}
  onPaymentResult={(result) => {
    if (result.errorMessage) {
      // Payment failed
      console.error('Payment failed:', result.errorMessage);
    } else if (result.status === 'succeeded') {
      // Payment succeeded
      console.log('Payment succeeded!');
    } else if (result.status === 'cancelled') {
      // User cancelled the payment
    }
  }}
  style={{ width: '100%', height: 600 }}
/>
)

Avoid placing the PaymentWidget inside a ScrollView. If necessary, ensure that the parent scroll is disabled while the user interacts with the widget to prevent scrolling conflicts.

1.5 onPaymentResult Callback

The onPaymentResult callback is triggered when the payment flow finishes. It provides a result object containing the payment outcome.

onPaymentResult={(result) => {
  console.log(result);
}}

// type result:  {
    status?: string;        // "succeeded", "cancelled", or "Failed"
    errorMessage?: string;  // Present if an error occurred
}

Congratulations! You have successfully integrated the Payment Widget into your application.

Props

Prop	Type	Required	Description
widgetId	string	true	A unique identifier for the widget instance
widgetType	string	optional	default is "PAYMENT_SHEET"
options	PresentPaymentSheetParams	true	Configuration and appearance options. When using PaymentWidget, pass the clientSecret & sdkAuthorization here instead of calling initPaymentSession.
onPaymentResult	(result: PaymentWidgetResult) => void	optional	Callback triggered when the payment completes, fails, or is cancelled
style	StyleProp<ViewStyle>	width & height are required	Defines the size and layout of the widget container

Troubleshooting

1. If you encounter issues related to the Android browser dependency, ensure that the required AndroidX Browser version is defined in your project.

Add the following versions in your root build.gradle (or version catalog equivalent):

ext {
    androidXBrowser = "1.8.0"
    androidXAnnotation = "1.7.1"
}