> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integration-guide/payment-experience/pay-then-vault/mobile/cross-platform/react-native/payment-widget.md).

# 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](https://github.com/juspay/react-native-hyperswitch/tree/main/example)

#### 1. Basic Usage

**1.1 Install the react native sdk**

```shellscript
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:

```shellscript
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.

```js
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`.

```js
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.

```js
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

```js
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:**

```typescript
// 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:**

```typescript
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.**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hyperswitch.io/integration-guide/payment-experience/pay-then-vault/mobile/cross-platform/react-native/payment-widget.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.