react-native-razorpay-elements

React Native wrapper for the Razorpay Elements SDK. Quick Buy is the first element.

In development. Not published yet.

| | | |---|---| | React Native | ≥ 0.76, New Architecture only (Fabric + TurboModule) | | Android | com.razorpay:razorpay-elements:1.0.0 | | iOS | Bundled RazorpayElements XCFramework + RazorpayCore pod | | Integration guide | docs/integration-guide.md | | Design, API, plan | docs/tech-design.md |

Usage

1. Configure once

import { RazorpayElements } from 'react-native-razorpay-elements';

await RazorpayElements.configure({
  keyId: 'rzp_live_…',            // required
  email: '[email protected]',     // optional
  customerId: 'cust_…',           // optional; with it, `contact` is optional
  theme: { fontColor: '#343434', buttonColor: '#000000' }, // optional RazorpayTheme
});

configure() applies once per app process; later calls are ignored and a JavaScript reload does not reset it. Resolve it before rendering <QuickBuy>. It rejects when keyId is missing or a value is invalid.

2. Render Quick Buy

Flow 1: order created before the screen opens

import { QuickBuy } from 'react-native-razorpay-elements';

<QuickBuy
  amount={49900}                 // paise
  currency="INR"
  contact="9876543210"
  orderId={order.id}
  buttonType="swipe"
  onPaymentSuccess={(result) => verifyOnServer(result)}   // razorpay_payment_id, _order_id, _signature
  onPaymentError={(e) => showError(e.code, e.error?.description)}
  onValidationError={(payload) => console.log(payload.reason)}
  onChangeMethods={openFullCheckout}
  onShowDefaultCheckout={openFullCheckout}
/>

Flow 2: order created when the buyer pays

Leave out orderId and pass onPaymentInitiateCreateOrder. Return the order ID from your server, or null to send it later with ref.set('order_id', id).

<QuickBuy
  amount={cartTotal}
  contact={buyer.phone}
  onPaymentInitiateCreateOrder={async ({ amount, currency }) => (await createOrder(amount, currency)).id}
  onPaymentSuccess={verifyOnServer}
/>

Without orderId or onPaymentInitiateCreateOrder, the native SDK's default order handling applies.

3. Update a running element

const quickBuy = useRef<QuickBuyRef>(null);

<QuickBuy ref={quickBuy} amount={cartTotal} … />

quickBuy.current?.set('order_id', 'order_…');     // e.g. Flow 2, order sent later
quickBuy.current?.set('amount', 59900);
const available = await quickBuy.current?.canMakePayment();

A value from set() stays until React changes that prop (latest write wins).

API

Props

| Prop | Type | When it applies | |---|---|---| | amount | number, paise | always; the element starts when it is > 0 | | currency | ISO 4217, default "INR" | always | | contact | string | always; required unless customerId was passed to configure | | email | string | always; unset uses the configure email | | orderId | string | Flow 1 | | buttonType | 'tap' | 'swipe', default 'tap' | before the element starts | | theme | QuickBuyTheme | before the element starts | | style | ViewStyle | outer container; the height comes from the content |

Events

| Callback | Payload | |---|---| | onPaymentSuccess | { razorpay_payment_id, razorpay_order_id?, razorpay_signature? }; verify the signature on your server | | onPaymentError | { code, error? }; code is an ErrorCode, error is the Razorpay error object | | onValidationError | { reason, … }, e.g. invalid_set_key | | onChangeMethods | the buyer tapped "More Options", or "Continue to checkout" when there is no recommended method; open your full checkout | | onShowDefaultCheckout | Quick Buy asks you to open your default checkout | | onPaymentInitiateCreateOrder | { amount, currency, orderId? } → Promise<string \| null> (Flow 2) |

QuickBuyRef

| Method | | |---|---| | set(key, value) | amount, currency, contact, customer_id, order_id, email | | canMakePayment() | Promise<boolean>; false for no methods, a failure, a timeout or an unmounted view |

ErrorCode

PAYMENT_CANCELED (0), NETWORK_ERROR (2), TLS_ERROR (6). Both platforms report the Android values.

Themes

| | RazorpayTheme | QuickBuyTheme | |---|---|---| | Passed to | configure({ theme }) | <QuickBuy theme> | | Scope | every element, for the app process | one element; overrides RazorpayTheme | | Tokens | themeColor, fontColor, fontStyle, fontWeight, fontSize, buttonColor | buttonColor, buttonRadius, buttonText ({amount} is replaced), amountFont{Color,Size,Weight}, instrumentFont{Color,Size,Weight}, changeMethodText (max 16), changeMethodFont{Color,Size,Weight} |

Colours are hex strings, sizes 10–16 (sp), weights 400/500/600/700. Unset tokens use the SDK default.

How it works

• RazorpayElements.configure calls the native RazorpayElements.configure through the RNRazorpayElements TurboModule.
• <QuickBuy> is the RNQuickBuy Fabric component. On each platform it hosts the native RazorpayQuickBuy view: the first commit creates it with every prop set, later commits send only the props that changed. Its height is measured natively and sent to React, so no fixed height is needed.
• SDK callbacks arrive as React events. An order request goes to onPaymentInitiateCreateOrder and its result is sent back to the SDK; set() and canMakePayment() are view commands.

Example app

A sample shop that mirrors the Android Elements sample: shop, checkout with Quick Buy pinned at the bottom, and the payment result. Settings cover the pay button (tap/swipe, order ID, order hook), the theme (presets, every token, the global theme) and a checkout config JSON. The checkout toolbar has a set() page and a canMakePayment() check. It uses the Android sample's test Key ID.

cd example && npm install
npx react-native run-android
cd ios && pod install && cd .. && npx react-native run-ios

Local development

To run against a local Elements build and the checkout repo's dev server (port 4400): publish a debug Elements AAR to mavenLocal as com.razorpay:razorpay-elements:1.0.0-local, then

cd example/android && ./gradlew assembleDebug -PrazorpayElementsVersion=1.0.0-local
adb reverse tcp:4400 tcp:4400

Without the property, the build uses the pinned 1.0.0.