@thepayulink/checkout-react-native 1.0.0 → 2.0.1

package/README.md

@@ -1,8 +1,14 @@
 # @thepayulink/checkout-react-native
 
-Elite Yatra / PayuLink UPI checkout for **React Native**. Opens the same secure hosted checkout used on the web inside a native full-screen modal (WebView), and bridges the payment result back to your app.
+PayuLink UPI checkout for **React Native**. Opens an order your server created in a native
+full-screen modal and hands your app the **signed payment result** to verify on your server.
 
-> Why a WebView? UPI collection, the QR, PayuLink signing and webhook verification all live on the Elite Yatra server. The app never touches secrets — it just shows the checkout and receives the confirmed result.
+Inside the modal is a WebView running the published PayuLink web checkout — the same script
+websites use — so the UPI QR, opening UPI apps, test mode and the signed result behave exactly
+as on the web.
+
+> **Upgrading from 1.x?** 1.0.0 no longer works (its hosted page was retired). See
+> [Upgrading from 1.x](#upgrading-from-1x) — it's a few prop changes.
 
 ## Install
 
@@ -11,41 +17,69 @@ npm install @thepayulink/checkout-react-native react-native-webview
 cd ios && pod install   # iOS only
 ```
 
-## Secure usage (recommended)
+On Android 11+, let the app see UPI apps — add inside `<manifest>` in `AndroidManifest.xml`:
+
+```xml
+<queries>
+  <intent>
+    <action android:name="android.intent.action.VIEW" />
+    <data android:scheme="upi" />
+  </intent>
+</queries>
+```
+
+On iOS, add the UPI app schemes you want to open to `LSApplicationQueriesSchemes` in
+`Info.plist` (for example `upi`, `phonepe`, `tez`, `paytmmp`).
+
+## Usage
 
-Create the order on **your backend** with the secret key, then pass the `orderId` to the app. The amount is fixed on the server and cannot be tampered with.
+1. **Your server** creates the order with the secret key — `POST /v1/orders` (or
+   `pl.orders.create()` with `@thepayulink/server`) — and returns `order.id` to the app.
+2. **The app** opens it with the publishable key.
+3. **Your server** verifies the handoff before fulfilling.
 
 ```jsx
 import React, { useState } from 'react';
 import { Button } from 'react-native';
-import PayulinkCheckout from '@thepayulink/checkout-react-native';
+import PayuLinkCheckout from '@thepayulink/checkout-react-native';
 
 export default function PayScreen() {
-  const [order, setOrder] = useState(null);
+  const [orderId, setOrderId] = useState(null);
 
   async function startPayment() {
-    // Call YOUR backend, which calls POST /api/orders with the secret key.
-    const { orderId } = await fetch('https://your-backend/create-order', {
+    // YOUR backend calls POST /v1/orders with the secret key and returns { orderId }.
+    const r = await fetch('https://api.yourapp.com/create-order', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ packageId: 'kailash-heli', travellers: 2 }),
-    }).then((r) => r.json());
-    setOrder(orderId);
+      body: JSON.stringify({ cartId: 'cart_42' }),
+    }).then((res) => res.json());
+    setOrderId(r.orderId);
   }
 
   return (
     <>
-      <Button title="Book ₹19,900" onPress={startPayment} />
-      {order && (
-        <PayulinkCheckout
+      <Button title="Pay ₹199.50" onPress={startPayment} />
+      {orderId && (
+        <PayuLinkCheckout
           visible
-          apiBase="https://eliteyatra.vip"
-          orderId={order}
-          publishableKey="pl_pk_live_xxxxx"
-          prefill={{ name: 'Asha', phone: '9876543210', email: 'asha@example.com' }}
-          onSuccess={(r) => { setOrder(null); console.log('Paid!', r.order_id, r.utr); }}
-          onDismiss={() => setOrder(null)}
-          onError={(e) => { setOrder(null); console.warn(e.message); }}
+          keyId="pl_live_xxxxxxxxxxxxxxxxxxxxxxxx"
+          orderId={orderId}
+          prefill={{ name: 'Asha', contact: '9876543210', email: 'asha@example.com' }}
+          theme={{ color: '#38BDF8' }}
+          onSuccess={async (handoff) => {
+            setOrderId(null);
+            // Verify on YOUR server — never trust the app alone.
+            await fetch('https://api.yourapp.com/verify', {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify(handoff),
+            });
+          }}
+          onDismiss={() => setOrderId(null)}
+          onError={(err) => {
+            setOrderId(null);
+            console.warn(err.code, err.message);   // e.g. GATEWAY_BUSY (err.retriable === true)
+          }}
         />
       )}
     </>
@@ -53,44 +87,64 @@ export default function PayScreen() {
 }
 ```
 
-## Convenience usage (amount from the app)
-
-Only if `PAYULINK_ALLOW_CLIENT_AMOUNT=1` on the server. Less secure — the amount is client-controlled.
+On your server, verify with `@thepayulink/server`:
 
-```jsx
-<PayulinkCheckout
-  visible={show}
-  apiBase="https://eliteyatra.vip"
-  amount={19900}
-  item="Kailash Mansarovar Yatra"
-  onSuccess={(r) => setShow(false)}
-  onDismiss={() => setShow(false)}
-/>
+```js
+if (!pl.verifyPaymentSignature(req.body)) return res.status(400).send('bad signature');
 ```
 
+Also rely on the `payin.verified` webhook: the customer may pay and close the app before
+`onSuccess` runs.
+
 ## Props
 
 | Prop | Type | Description |
 | --- | --- | --- |
-| `visible` | boolean | Show/hide the checkout modal. |
-| `apiBase` | string | Pay server URL. Default `https://eliteyatra.vip`. |
-| `orderId` | string | Secure: backend-created order id. |
-| `amount` | number | Convenience: rupees (ignored if `orderId` set). |
-| `item` | string | Description (convenience flow). |
-| `publishableKey` | string | `pl_pk_…`, safe to embed. |
-| `prefill` | object | `{ name, phone, email }`. |
-| `onSuccess` | function | `({ order_id, utr, amount })`. Fired once, server-confirmed. |
-| `onDismiss` | function | User closed / hardware back. |
-| `onError` | function | Load or order error. |
+| `keyId` | string | **Required.** Publishable key, `pl_live_…` or `pl_test_…`. |
+| `orderId` | string | **Required.** `order_…` from `POST /v1/orders`. |
+| `visible` | boolean | Show or hide the modal. Default `true`. |
+| `prefill` | object | `{ name, contact, email }`. |
+| `theme` | object | `{ color }` — brand colour of the checkout panel. |
+| `name` | string | Overrides the merchant name in the header. |
+| `onSuccess` | function | Receives the signed handoff: `payulink_order_id`, `payulink_payment_id`, `payulink_signature`, `utr`, `amount` (paise), plus `order_id` / `payment_id` aliases. |
+| `onDismiss` | function | The customer closed the checkout, or pressed Android back. |
+| `onError` | function | An `Error` with `code` and `retriable`: `GATEWAY_BUSY` (retriable), `ORDER_EXPIRED`, `ORDER_ALREADY_PAID`, `UPI_APP_NOT_FOUND`, `SCRIPT_LOAD_FAILED`, `INVALID_OPTIONS`, … |
+| `apiBase` | string | Default `https://payulink.io/api`. |
+| `scriptUrl` | string | Web checkout script. Default: the pinned PayuLink CDN build. |
+| `style` | style | Style for the modal's container. |
+
+Passing a `keySecret` throws — the secret belongs on your server only. There is no `amount`
+prop: amounts are fixed by your server when it creates the order.
+
+## Test mode
+
+With a `pl_test_` key (and an order created with the same test key), the checkout shows a
+**TEST** badge and *Simulate success* / *Simulate failure* buttons. No real money moves;
+`onSuccess` receives a handoff signed with the test key's secret, so your verify step is
+exercised end to end.
+
+## Promise helper
 
-## Important: confirm server-side
+```jsx
+import { createCheckout } from '@thepayulink/checkout-react-native';
+
+const { Component, promise } = createCheckout({ keyId, orderId });
+// render <Component /> somewhere, then:
+const handoff = await promise;   // rejects on dismiss (code DISMISSED) or error
+```
 
-`onSuccess` is triggered by the webhook-verified status streamed from the server — reliable for UX. For anything money-critical (unlocking a booking, sending tickets), still verify on **your backend** by reading the order status or handling the PayuLink webhook. Never trust the client alone.
+## Upgrading from 1.x
 
-## Expo
+| 1.x | 2.x |
+| --- | --- |
+| `publishableKey="pl_pk_…"` | `keyId="pl_live_…"` (`publishableKey` still accepted) |
+| `amount` / `item` (app sets the price) | Removed — create the order on your server |
+| `prefill.phone` | `prefill.contact` (`phone` still accepted) |
+| `onSuccess({ order_id, utr, amount })` | Signed handoff — verify `payulink_signature` on your server |
+| Loaded `…/api/pay` (retired, returns 404) | Runs the PayuLink web checkout |
 
-Works with Expo (Dev Client / prebuild) since it needs `react-native-webview`. It does **not** work in Expo Go if your Expo SDK's Go build excludes the WebView native module — use a development build.
+The default export is now `PayuLinkCheckout`; the 1.x name `PayulinkCheckout` is still exported.
 
 ## License
 
-UNLICENSED — internal to Elite Yatra.
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thepayulink/checkout-react-native",
-  "version": "1.0.0",
-  "description": "Elite Yatra / PayuLink UPI checkout for React Native — opens the secure hosted checkout in a native modal.",
+  "version": "2.0.1",
+  "description": "PayuLink UPI checkout for React Native — opens a server-created order and returns the signed payment result.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "files": [
@@ -9,7 +9,6 @@
     "README.md"
   ],
   "keywords": [
-    "eliteyatra",
     "payulink",
     "react-native",
     "payment",
@@ -21,6 +20,7 @@
     "react-native": ">=0.64.0",
     "react-native-webview": ">=11.0.0"
   },
-  "author": "Elite Yatra",
-  "license": "MIT"
+  "author": "PayuLink",
+  "license": "MIT",
+  "homepage": "https://payulink.io"
 }

package/src/html.js

@@ -0,0 +1,87 @@
+// Builds the page the React Native WebView renders: the published PayuLink web checkout
+// (the same script websites use, served from the PayuLink CDN), opened on a server-created
+// order, with its callbacks bridged to the app through window.ReactNativeWebView.postMessage.
+//
+// Kept free of React Native imports so it can be tested in a plain browser.
+
+export const DEFAULT_API_BASE = 'https://payulink.io/api';
+export const CHECKOUT_SCRIPT_URL = 'https://assetcdn.payulink.io/checkout/v1/checkout-2.2.1.js';
+
+// UPI and wallet app schemes a payment page may hand off to.
+export const APP_LINK = /^(upi|intent|tez|gpay|phonepe|paytmmp|paytm|bhim|credpay|mobikwik|amazonpay|whatsapp):/i;
+
+// JSON that is safe inside an inline <script>: no "</script>", no line separators.
+function scriptJson(value) {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/[\u2028\u2029]/g, (c) => '\\u' + c.charCodeAt(0).toString(16));
+}
+
+function attr(value) {
+  return String(value).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.keyId      Publishable key (pl_live_… / pl_test_…)
+ * @param {string} o.orderId    Order created by your server (POST /v1/orders)
+ * @param {object} [o.prefill]  { name, contact, email }
+ * @param {object} [o.theme]    { color }
+ * @param {string} [o.name]     Header title override
+ * @param {string} [o.apiBase]
+ * @param {string} [o.scriptUrl]  Web checkout script to load (defaults to the pinned CDN build)
+ */
+export function buildCheckoutHtml(o) {
+  const config = {
+    key: o.keyId,
+    orderId: o.orderId,
+    prefill: o.prefill || {},
+    theme: o.theme || undefined,
+    name: o.name || undefined,
+    apiBase: o.apiBase || DEFAULT_API_BASE,
+  };
+  const src = o.scriptUrl || CHECKOUT_SCRIPT_URL;
+  return `<!doctype html>
+<html><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
+<style>html,body{margin:0;min-height:100%;background:#0b1f33;}</style>
+<script src="${attr(src)}"></script>
+</head><body>
+<script>
+(function () {
+  var cfg = ${scriptJson(config)};
+  var appLink = ${APP_LINK.toString()};
+  function post(msg) {
+    try { window.ReactNativeWebView.postMessage(JSON.stringify(msg)); } catch (e) {}
+  }
+  // UPI app buttons are links with upi:// (or similar) targets; the app opens them natively.
+  document.addEventListener('click', function (e) {
+    var a = e.target && e.target.closest ? e.target.closest('a[href]') : null;
+    var href = a ? a.getAttribute('href') || '' : '';
+    if (appLink.test(href)) { e.preventDefault(); post({ type: 'open_url', url: href }); }
+  }, true);
+  if (typeof window.PayuLink !== 'function') {
+    post({ type: 'error', code: 'SCRIPT_LOAD_FAILED', retriable: true,
+           message: 'Could not load the PayuLink checkout. Check the internet connection and try again.' });
+    return;
+  }
+  try {
+    new window.PayuLink({ key: cfg.key, apiBase: cfg.apiBase, name: cfg.name, theme: cfg.theme }).open({
+      order_id: cfg.orderId,
+      prefill: cfg.prefill,
+      handler: function (result) { post({ type: 'success', result: result }); },
+      onDismiss: function () { post({ type: 'dismiss' }); },
+      onError: function (err) {
+        post({ type: 'error', code: err && err.code, retriable: !!(err && err.retriable),
+               message: (err && err.message) || 'Checkout error' });
+      }
+    });
+  } catch (e) {
+    post({ type: 'error', code: 'CHECKOUT_FAILED', message: e && e.message });
+  }
+})();
+</script>
+</body></html>`;
+}

package/src/index.d.ts

@@ -1,41 +1,72 @@
 import * as React from 'react';
 import { StyleProp, ViewStyle } from 'react-native';
 
-export interface PayulinkPrefill {
+export interface PayuLinkPrefill {
   name?: string;
-  phone?: string;
+  /** 10-digit mobile number. `phone` and `mobile` are accepted as aliases. */
   contact?: string;
+  phone?: string;
   mobile?: string;
   email?: string;
 }
 
-export interface PayulinkSuccess {
-  order_id: string;
-  utr: string | null;
+/** The signed handoff. Send it to YOUR server and verify `payulink_signature` there. */
+export interface PayuLinkSuccess {
+  payulink_order_id: string;
+  payulink_payment_id: string;
+  /** lowercase hex HMAC_SHA256(order_id + "|" + payment_id, key_secret) */
+  payulink_signature: string;
+  utr?: string | null;
+  /** PAISE */
   amount?: number;
+  /** Aliases of payulink_order_id / payulink_payment_id. */
+  order_id: string;
+  payment_id: string;
+}
+
+export interface PayuLinkCheckoutError extends Error {
+  /** e.g. GATEWAY_BUSY, ORDER_EXPIRED, UPI_APP_NOT_FOUND, SCRIPT_LOAD_FAILED, INVALID_OPTIONS */
+  code?: string;
+  retriable: boolean;
 }
 
-export interface PayulinkCheckoutProps {
+export interface PayuLinkCheckoutProps {
+  /** Show or hide the checkout. Default true. */
   visible?: boolean;
-  /** Elite Yatra pay server base URL. Default: https://eliteyatra.vip */
-  apiBase?: string;
-  /** SECURE flow: order id created by your backend via POST /api/orders. */
-  orderId?: string;
-  /** Convenience flow: amount in rupees (ignored when orderId is set). */
-  amount?: number;
-  item?: string;
-  /** Publishable key (pl_pk_…). Safe to embed. */
+  /** Publishable key: pl_live_… / pl_test_…. Never a key_secret. */
+  keyId?: string;
+  /** 1.x name for `keyId`. */
   publishableKey?: string;
-  prefill?: PayulinkPrefill;
-  onSuccess?: (result: PayulinkSuccess) => void;
+  /** Required. Created by YOUR server via POST /v1/orders. */
+  orderId: string;
+  prefill?: PayuLinkPrefill;
+  /** Brand colour of the checkout panel, e.g. { color: '#38BDF8' }. */
+  theme?: { color?: string };
+  /** Overrides the merchant name in the header. */
+  name?: string;
+  /** Default https://payulink.io/api */
+  apiBase?: string;
+  /** Web checkout script to load. Default: the pinned PayuLink CDN build. */
+  scriptUrl?: string;
+  onSuccess?: (handoff: PayuLinkSuccess) => void;
+  /** The customer closed the checkout (or pressed Android back). */
   onDismiss?: () => void;
-  onError?: (error: Error) => void;
+  onError?: (error: PayuLinkCheckoutError) => void;
   style?: StyleProp<ViewStyle>;
 }
 
-export default function PayulinkCheckout(props: PayulinkCheckoutProps): React.JSX.Element;
+export default function PayuLinkCheckout(props: PayuLinkCheckoutProps): React.JSX.Element | null;
+export { PayuLinkCheckout };
+/** 1.x name. */
+export const PayulinkCheckout: typeof PayuLinkCheckout;
 
-export function createCheckout(options: Omit<PayulinkCheckoutProps, 'visible'>): {
-  Component: (extra?: Partial<PayulinkCheckoutProps>) => React.JSX.Element;
-  promise: Promise<PayulinkSuccess>;
+export function createCheckout(options: Omit<PayuLinkCheckoutProps, 'visible' | 'onSuccess' | 'onDismiss' | 'onError'>): {
+  Component: (extra?: Partial<PayuLinkCheckoutProps>) => React.JSX.Element | null;
+  promise: Promise<PayuLinkSuccess>;
 };
+
+export function buildCheckoutHtml(options: {
+  keyId: string; orderId: string; prefill?: PayuLinkPrefill; theme?: { color?: string }; name?: string; apiBase?: string; scriptUrl?: string;
+}): string;
+export const DEFAULT_API_BASE: string;
+export const CHECKOUT_SCRIPT_URL: string;

package/src/index.js

@@ -1,139 +1,187 @@
 // @thepayulink/checkout-react-native
-// Renders the Elite Yatra hosted checkout inside a native full-screen Modal +
-// WebView, and bridges success/dismiss events back to JS via postMessage.
+// Opens a server-created PayuLink order in a native full-screen Modal. Inside is a WebView
+// running the published PayuLink web checkout (the same script websites use), so the UPI QR,
+// app hand-off, test mode and the signed result all behave exactly as on the web.
 import React from 'react';
-import { Modal, View, ActivityIndicator, StyleSheet, BackHandler, Platform } from 'react-native';
+import { Modal, View, SafeAreaView, ActivityIndicator, StyleSheet, BackHandler, Platform, Linking } from 'react-native';
 import { WebView } from 'react-native-webview';
+import { buildCheckoutHtml, DEFAULT_API_BASE, CHECKOUT_SCRIPT_URL, APP_LINK } from './html';
 
-const DEFAULT_API_BASE = 'https://eliteyatra.vip';
+export { buildCheckoutHtml, DEFAULT_API_BASE, CHECKOUT_SCRIPT_URL };
 
-function buildUrl(apiBase, params) {
-  const base = String(apiBase || DEFAULT_API_BASE).replace(/\/$/, '');
-  const q = Object.entries(params)
-    .filter(([, v]) => v != null && v !== '')
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join('&');
-  return `${base}/pay${q ? `?${q}` : ''}`;
+const KEY_ID = /^pl_(live|test)_[0-9a-f]{24}$/;
+
+function checkoutError(message, code, retriable) {
+  const e = new Error(message);
+  e.code = code;
+  e.retriable = !!retriable;
+  return e;
 }
 
 /**
- * <PayulinkCheckout /> — controlled component.
+ * <PayuLinkCheckout /> — controlled component.
  *
- * <PayulinkCheckout
- *   visible={show}
- *   apiBase="https://eliteyatra.vip"
- *   orderId={orderId}                 // SECURE: created by your backend (recommended)
- *   // or: amount={19900} item="Tour"  // convenience flow
- *   publishableKey="pl_pk_live_…"
- *   prefill={{ name, phone, email }}
- *   onSuccess={(r) => {}}             // { order_id, utr, amount }
- *   onDismiss={() => setShow(false)}
- *   onError={(e) => {}}
+ * <PayuLinkCheckout
+ *   visible={!!orderId}
+ *   keyId="pl_live_…"                 // publishable key — safe in the app
+ *   orderId={orderId}                 // created by YOUR server: POST /v1/orders
+ *   prefill={{ name, contact, email }}
+ *   onSuccess={(handoff) => {}}       // send to your server and verify the signature there
+ *   onDismiss={() => setOrderId(null)}
+ *   onError={(err) => {}}             // err.code, e.g. GATEWAY_BUSY (err.retriable === true)
  * />
  */
-export default function PayulinkCheckout(props) {
+export default function PayuLinkCheckout(props) {
   const {
     visible = true,
-    apiBase = DEFAULT_API_BASE,
-    orderId,
-    amount,
-    item,
+    keyId: keyIdProp,
     publishableKey,
-    prefill = {},
+    orderId,
+    prefill,
+    theme,
+    name,
+    apiBase = DEFAULT_API_BASE,
+    scriptUrl,
     onSuccess,
     onDismiss,
     onError,
     style,
   } = props;
 
-  const uri = React.useMemo(
-    () => buildUrl(apiBase, {
-      order_id: orderId,
-      key: publishableKey,
-      amount: orderId ? undefined : amount,
-      item: orderId ? undefined : item,
-      name: prefill.name,
-      phone: prefill.phone || prefill.contact || prefill.mobile,
-      email: prefill.email,
-      back: '', // no in-page navigation; the app owns closing
-    }),
-    [apiBase, orderId, amount, item, publishableKey, prefill.name, prefill.phone, prefill.contact, prefill.mobile, prefill.email]
+  if (props.keySecret || props.key_secret) {
+    throw new Error('PayuLink: never pass a key_secret to the app. It belongs on your server only.');
+  }
+  if (props.amount != null) {
+    throw new Error('PayuLink: `amount` is not supported. Create the order on your server (POST /v1/orders) and pass `orderId`.');
+  }
+
+  const keyId = keyIdProp || publishableKey;
+  const invalid = !keyId || !KEY_ID.test(keyId)
+    ? 'PayuLink: `keyId` must be your publishable key (pl_live_… or pl_test_…).'
+    : !orderId || !/^order_[0-9a-f]{20}$/.test(orderId)
+      ? 'PayuLink: `orderId` must be an order id from POST /v1/orders (order_…).'
+      : null;
+
+  const p = prefill || {};
+  const html = React.useMemo(
+    () => (invalid ? null : buildCheckoutHtml({
+      keyId,
+      orderId,
+      prefill: { name: p.name, contact: p.contact || p.phone || p.mobile, email: p.email },
+      theme,
+      name,
+      apiBase,
+      scriptUrl,
+    })),
+    [invalid, keyId, orderId, p.name, p.contact, p.phone, p.mobile, p.email, theme && theme.color, name, apiBase, scriptUrl]
   );
 
   const settled = React.useRef(false);
-  React.useEffect(() => { if (visible) settled.current = false; }, [visible]);
+  React.useEffect(() => { if (visible) settled.current = false; }, [visible, orderId]);
+
+  React.useEffect(() => {
+    if (visible && invalid && onError) onError(checkoutError(invalid, 'INVALID_OPTIONS', false));
+  }, [visible, invalid]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // Android hardware back closes the sheet.
   React.useEffect(() => {
-    if (!visible || Platform.OS !== 'android') return;
+    if (!visible || Platform.OS !== 'android') return undefined;
     const sub = BackHandler.addEventListener('hardwareBackPress', () => {
-      onDismiss && onDismiss();
+      if (onDismiss) onDismiss();
       return true;
     });
     return () => sub.remove();
   }, [visible, onDismiss]);
 
+  const openApp = (url) => {
+    Linking.openURL(url).catch(() => {
+      if (onError) {
+        onError(checkoutError('No UPI app on this phone could open the payment. Install a UPI app, or pay by scanning the QR from another phone.',
+          'UPI_APP_NOT_FOUND', true));
+      }
+    });
+  };
+
   const handleMessage = (event) => {
     let msg;
-    try { msg = JSON.parse(event.nativeEvent.data); } catch { return; }
-    switch (msg && msg.type) {
-      case 'checkout.success':
+    try { msg = JSON.parse(event.nativeEvent.data); } catch (e) { return; }
+    if (!msg || typeof msg.type !== 'string') return;
+    switch (msg.type) {
+      case 'success': {
         if (settled.current) return;
         settled.current = true;
-        onSuccess && onSuccess({ order_id: msg.order_id, utr: msg.utr || null, amount: msg.amount });
+        const r = msg.result || {};
+        // The signed handoff, plus the short aliases 1.x apps read.
+        if (onSuccess) onSuccess({ ...r, order_id: r.payulink_order_id, payment_id: r.payulink_payment_id });
         break;
-      case 'checkout.dismiss':
-        onDismiss && onDismiss();
+      }
+      case 'dismiss':
+        if (onDismiss) onDismiss();
         break;
-      case 'checkout.error':
-        onError && onError(new Error(msg.error || 'Checkout error'));
+      case 'error':
+        if (onError) onError(checkoutError(msg.message || 'Checkout error', msg.code, msg.retriable));
+        break;
+      case 'open_url':
+        if (typeof msg.url === 'string' && APP_LINK.test(msg.url)) openApp(msg.url);
         break;
       default:
         break;
     }
   };
 
+  if (invalid) return null;
+
   return (
     <Modal visible={visible} animationType="slide" transparent={false} onRequestClose={() => onDismiss && onDismiss()}>
-      <View style={[styles.fill, style]}>
+      {/* SafeAreaView keeps the checkout's header (merchant, amount) clear of the notch / Dynamic Island. */}
+      <SafeAreaView style={[styles.fill, style]}>
         <WebView
-          source={{ uri }}
-          onMessage={handleMessage}
-          startInLoadingState
-          renderLoading={() => (
-            <View style={styles.loading}><ActivityIndicator size="large" /></View>
-          )}
-          onError={(e) => onError && onError(new Error(e.nativeEvent.description || 'WebView error'))}
+          source={{ html, baseUrl: 'https://payulink.io' }}
           originWhitelist={['*']}
           javaScriptEnabled
           domStorageEnabled
-          // Let UPI apps open from upi:// intent links.
-          onShouldStartLoadWithRequest={(r) => {
-            if (/^(upi|tez|phonepe|paytmmp|gpay|intent):/i.test(r.url)) return true;
-            return true;
+          setSupportMultipleWindows={false}
+          onMessage={handleMessage}
+          // A page navigation to upi:// (or another app) opens that app instead of the WebView.
+          onShouldStartLoadWithRequest={(req) => {
+            const url = (req && req.url) || '';
+            if (/^(https?|about|data|blob):/i.test(url)) return true;
+            if (APP_LINK.test(url)) openApp(url);
+            return false;
           }}
+          startInLoadingState
+          renderLoading={() => (
+            <View style={styles.loading}><ActivityIndicator size="large" color="#2dd4bf" /></View>
+          )}
+          onError={(e) => onError && onError(checkoutError(
+            (e && e.nativeEvent && e.nativeEvent.description) || 'Could not load the checkout.', 'WEBVIEW_ERROR', true))}
         />
-      </View>
+      </SafeAreaView>
     </Modal>
   );
 }
 
+// 1.x name, kept so existing imports keep compiling.
+export const PayulinkCheckout = PayuLinkCheckout;
+export { PayuLinkCheckout };
+
 /**
- * Imperative helper for apps that prefer a promise over a component.
- * Returns { Component, promise }. Render <Component/> once; the promise
- * resolves on success and rejects on dismiss/error.
- *
- * Most apps should just use the <PayulinkCheckout/> component above.
+ * Promise-style helper. Returns { Component, promise }: render <Component /> once; the promise
+ * resolves with the signed handoff and rejects on dismiss or error.
  */
 export function createCheckout(options) {
-  let resolve, reject;
+  let resolve;
+  let reject;
   const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+  // A dismiss before the app awaits must not surface as an unhandled rejection; callers that
+  // await or .catch() still receive it.
+  promise.catch(() => {});
   const Component = (extra) => (
-    <PayulinkCheckout
+    <PayuLinkCheckout
       {...options}
       {...extra}
       onSuccess={(r) => resolve(r)}
-      onDismiss={() => reject(new Error('dismissed'))}
+      onDismiss={() => reject(checkoutError('Checkout dismissed', 'DISMISSED', false))}
       onError={(e) => reject(e)}
     />
   );
@@ -141,6 +189,6 @@ export function createCheckout(options) {
 }
 
 const styles = StyleSheet.create({
-  fill: { flex: 1, backgroundColor: '#0d1117' },
+  fill: { flex: 1, backgroundColor: '#0b1f33' },
   loading: { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, alignItems: 'center', justifyContent: 'center' },
 });