Payment Element

Implement embedded payment widget in React Native applications

The PaymentElement component from Juspay Hyperswitch 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.

Find the Demo App

Find the demo app here

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 Initialize Hyperswitch

Initialize Hyperswitch once using your publishable key and profile ID. Reuse the same initialized instance throughout your application.

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

const hyperPromise = Hyperswitch.init({
      publishableKey: 'pk_snd_xxxxxxxx',   // from Hyperswitch dashboard
      profileId: 'pro_xxxxxxxx',           // your profile id
      // environment: 'SANDBOX',           // 'PROD' (default) | 'SANDBOX' | 'INTEG'
    });

Keep the Hyperswitch secret API key on your backend only. The app should never handle it.

1.2 Get sdk_authorization from your Backend

Call your payment-creation endpoint. Its JSON response must contain sdk_authorization.

const response = await fetch('https://your-server.com/create-payment-intent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 6500, currency: 'USD', customer_id: 'cust_123' }),
});

const { sdk_authorization } = await response.json();

1.3 Wrap your app with HyperElements

To use HyperSwitch hooks and the Embedded UI in a React Native application, wrap your payment screen with the HyperElements component. During initialization, you must provide the required sdkAuthorization prop to HyperElements. This authorization is necessary for the SDK to initialize correctly.

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

<HyperElements hyper={hyperPromise} options={{ sdkAuthorization }}>
  <CheckoutScreen />
</HyperElements>

1.4 Render your Payment Element

Use the Hyperswitch PaymentElement component to render an embedded payment form

import { useRef } from 'react';
import {
  PaymentElement,
  type PaymentElementHandle,
  type PaymentResult,
} from '@juspay-tech/react-native-hyperswitch';

export default function PaymentUI() {
  const paymentRef = useRef<PaymentElementHandle>(null);
  // rest of your logic
  return (
    <PaymentElement
      widgetId="checkout-widget"
      ref={paymentRef}
      options={{
        merchantDisplayName: 'My Store',
        appearance: { theme: 'Light' },
        subscribedEvents: ['PAYMENT_METHOD_STATUS', 'FORM_STATUS'],
      }}
      onPaymentResult={(result) => handleResult(result)}
      onChange={(event) => {
        if (event.eventName === 'PAYMENT_METHOD_STATUS') setReady(true);
      }}
      style={{ width: '100%', height: 600 }}
    />
  );
}

1.5 Confirm from your own button:

// Option A — via context (works anywhere inside HyperElements)
const result = await widgets.confirmPayment(paymentRef, { confirmParams: {} });

// Option B — via the ref directly
const result = await paymentRef.current?.confirmPayment();

handleResult(result);

1.6 Handle the result:

async function handleResult(result: PaymentResult) {
  if (result.status === 'completed') {
    // payment succeeded
  } else if (result.status === 'canceled') {
    // user dismissed the sheet
  } else {
    console.log(`${result.type}: ${result.message}`);
  }
}

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