@boostengine/payments 1.0.0 → 1.1.1

package/README.md

@@ -1,39 +1,91 @@
-# @boostengine/payments
+# @boostengine/payments 💳
 
-> **Unified Multi-Gateway Payment Orchestration Layer** for Indian & Global eCommerce. Seamlessly plug in **Razorpay, Cashfree, PhonePe, Paytm, Stripe, and COD** through a single unified API with smart routing, automatic fallbacks, and signature verification.
+[![npm version](https://img.shields.io/npm/v/@boostengine/payments.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/@boostengine/payments)
+[![npm downloads](https://img.shields.io/npm/dm/@boostengine/payments.svg?style=flat-square&color=green)](https://www.npmjs.com/package/@boostengine/payments)
+[![license](https://img.shields.io/npm/l/@boostengine/payments.svg?style=flat-square)](https://github.com/boostengine/boostengine/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178c6.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![Gateways](https://img.shields.io/badge/Gateways-Razorpay%20%7C%20Cashfree%20%7C%20PhonePe%20%7C%20Paytm%20%7C%20Stripe%20%7C%20COD-purple.svg?style=flat-square)](https://npmjs.com/package/@boostengine/payments)
+
+> **Unified multi-gateway payment orchestration for Indian and global eCommerce. Connect Razorpay, Cashfree, PhonePe, Paytm, Stripe, and Cash on Delivery (COD) with a single, unified API. Features automatic gateway failover, smart currency routing, Next.js webhook normalizers, and React checkout hooks.**
+
+Zero dependency bloat — uses native Node.js `crypto` and `fetch`. No need to install 6 separate heavy vendor SDKs.
 
 ---
 
-## ⚡ Why @boostengine/payments?
+## 📸 Architecture & Payment Flow
+
+```text
+  Customer Clicks "Pay Now" (₹1,499)
+                 │
+                 ▼
+  ┌─────────────────────────────────────────────────────────────┐
+  │                 Smart Payment Orchestrator                  │
+  ├─────────────────────────────────────────────────────────────┤
+  │ Currency Routing:                                           │
+  │   - If INR  ──► Route to Cashfree / Razorpay / PhonePe      │
+  │   - If USD  ──► Route to Stripe                             │
+  │   - If COD  ──► Verify min/max limits & add handling fee    │
+  │                                                             │
+  │ High-Availability Failover:                                 │
+  │   [Cashfree Server 500] ──► Auto-retry with [Razorpay] ──► OK│
+  └──────────────────────────────┬──────────────────────────────┘
+                                 │
+                                 ▼
+  ┌─────────────────────────────────────────────────────────────┐
+  │              Client Checkout Hook (`useBoostPayment`)        │
+  ├─────────────────────────────────────────────────────────────┤
+  │ Opens Razorpay Popup / Cashfree Dropin / PhonePe App / UPI  │
+  └──────────────────────────────┬──────────────────────────────┘
+                                 │
+                                 ▼
+  ┌─────────────────────────────────────────────────────────────┐
+  │              Next.js Webhook Handler (2 Lines)              │
+  ├─────────────────────────────────────────────────────────────┤
+  │ Validates HMAC-SHA256 signature and returns normalized event:│
+  │   'PAYMENT_SUCCESS' | 'PAYMENT_FAILED' | 'REFUND_PROCESSED' │
+  └─────────────────────────────────────────────────────────────┘
+```
+
+---
 
-- 🔌 **Unified API**: Write your payment flow once. Switch or combine Razorpay, Cashfree, PhonePe, or Stripe without rewriting checkout logic.
-- 🛡️ **Smart Fallback**: If your primary payment gateway has a downtime or failure, transactions automatically failover to your secondary gateway!
-- 💱 **Multi-Currency Auto-Routing**: Automatically route USD/EUR to Stripe and INR to Razorpay/Cashfree/PhonePe.
-- 🔐 **Built-in Signature Verification**: Native verification for Razorpay HMAC, Cashfree webhook, PhonePe SHA-256 + Salt `X-VERIFY`, and Stripe webhooks.
-- 🪶 **Zero Dependency Bloat**: Uses native Node.js `fetch` and `crypto`. No 10 heavy third-party vendor SDKs.
+## 🌟 Gateway Comparison
+
+| Gateway | Supported Currencies | Methods Supported | Best For |
+| :--- | :--- | :--- | :--- |
+| **Razorpay** | INR, USD, EUR + 90 more | UPI, Cards, NetBanking, Wallets, EMI | Reliable Indian D2C checkout |
+| **Cashfree** | INR | Instant UPI QR, Intent, NetBanking, Cards | Low transaction fees & high UPI success |
+| **PhonePe** | INR | PhonePe App, UPI Intent, QR Code | Fast mobile conversions in India |
+| **Stripe** | Global (135+ currencies) | Credit/Debit Cards, Apple Pay, Google Pay | International cross-border sales |
+| **Paytm** | INR | Paytm Wallet, UPI, Postpaid, NetBanking | Indian mobile users |
+| **Cash on Delivery** | Any | Pay in cash upon delivery | Tier 2/3 Indian cities |
 
 ---
 
 ## 📦 Installation
 
 ```bash
+# npm
 npm install @boostengine/payments
+
+# pnpm
+pnpm add @boostengine/payments
+
+# yarn
+yarn add @boostengine/payments
 ```
 
 ---
 
-## 🚀 Quickstart
+## 🚀 Step-by-Step Integration Guide
 
-### 1. Initialize PaymentManager
+### Step 1: Initialize Payment Manager (`lib/payments.ts`)
 
 ```typescript
 import { createPaymentManager } from '@boostengine/payments';
 
 export const payments = createPaymentManager({
-  // Default gateway when none is specified
   defaultGateway: 'cashfree',
 
-  // Configure any or all gateways
   gateways: {
     cashfree: {
       appId: process.env.CASHFREE_APP_ID!,
@@ -58,11 +110,11 @@ export const payments = createPaymentManager({
     cod: {
       minOrderValue: 200,
       maxOrderValue: 10000,
-      extraFee: 49, // Rs. 49 COD handling charge
+      extraFee: 49, // ₹49 COD handling charge
     },
   },
 
-  // Smart Routing & Fallbacks
+  // Smart Routing & High Availability
   smartRouting: {
     currencyMap: {
       USD: 'stripe',
@@ -76,122 +128,142 @@ export const payments = createPaymentManager({
 
 ---
 
-### 2. Create an Order (Single or Multi-Gateway)
+### Step 2: Create Order API Route (`app/api/checkout/route.ts`)
+
+Pass standard human amounts (e.g. `1499.00`). Paise and cents conversion is handled automatically!
 
 ```typescript
-// Works identically across Cashfree, Razorpay, PhonePe, Stripe, and COD!
-const order = await payments.createOrder({
-  amount: 1499.00,
-  currency: 'INR',
-  receipt: `order_${Date.now()}`,
-  customer: {
-    name: 'Aman Sharma',
-    email: 'aman@example.com',
-    phone: '9876543210',
-  },
-  // Optionally override gateway per checkout button:
-  // gateway: 'razorpay' | 'phonepe' | 'cashfree' | 'stripe' | 'cod'
-});
+import { payments } from '@/lib/payments';
+
+export async function POST(req: Request) {
+  const { amount, customer, gateway } = await req.json();
+
+  // Create order with automatic fallback if primary gateway is down
+  const order = await payments.createOrderWithFallback({
+    amount: amount, // e.g. 1499
+    currency: 'INR',
+    receipt: `order_${Date.now()}`,
+    customer: {
+      name: customer.name,
+      email: customer.email,
+      phone: customer.phone,
+    },
+    fallbackChain: gateway ? [gateway, 'razorpay'] : ['cashfree', 'razorpay'],
+  });
 
-console.log(order);
-/*
-Output:
-{
-  gateway: 'cashfree',
-  orderId: 'order_1709923812',
-  gatewayOrderId: 'order_1709923812',
-  amount: 1499,
-  currency: 'INR',
-  status: 'CREATED',
-  paymentSessionId: 'session_cf_109283719283', // Ready for Cashfree Dropin
-  redirectUrl: '...',                          // Available for PhonePe / Stripe
-  rawResponse: { ... }
+  return Response.json(order);
 }
-*/
 ```
 
 ---
 
-### 3. Smart Fallback (High-Availability Checkout)
-
-If your primary payment gateway experiences bank server outages or 500 errors, automatic fallback routes the order through the next available gateway:
-
-```typescript
-const order = await payments.createOrderWithFallback({
-  amount: 1499.00,
-  currency: 'INR',
-  receipt: `order_${Date.now()}`,
-  customer: {
-    name: 'Aman Sharma',
-    email: 'aman@example.com',
-    phone: '9876543210',
-  },
-  fallbackChain: ['razorpay', 'cashfree', 'phonepe'],
-});
-```
-
----
-
-### 4. Verify Payment & Webhooks
-
-```typescript
-// 1. Verify frontend checkout completion:
-const verification = await payments.verifyPayment({
-  gateway: 'razorpay',
-  orderId: 'order_123',
-  paymentId: 'pay_456',
-  signature: req.body.razorpay_signature,
-});
-
-if (verification.isSuccessful) {
-  console.log(`Payment confirmed! ID: ${verification.paymentId}`);
-}
-
-// 2. Universal Webhook Authenticator:
-const webhook = await payments.verifyWebhook({
-  gateway: 'cashfree', // or 'razorpay' | 'phonepe' | 'stripe'
-  rawBody: req.rawBody,
-  headers: req.headers,
-});
-
-if (webhook.isValid) {
-  console.log(`Verified webhook event: ${webhook.event}`, webhook.data);
+### Step 3: Frontend Checkout Button (`components/CheckoutButton.tsx`)
+
+The `useBoostPayment` hook automatically injects the right vendor scripts on demand and displays payment modals:
+
+```tsx
+'use client';
+
+import { useBoostPayment } from '@boostengine/payments/react';
+import { useRouter } from 'next/navigation';
+
+export default function CheckoutButton({ cartTotal, customer }: any) {
+  const router = useRouter();
+  const { openPaymentModal, isProcessing } = useBoostPayment();
+
+  const handlePay = async (gateway: 'razorpay' | 'cashfree' | 'phonepe' | 'cod') => {
+    // 1. Create order on server
+    const res = await fetch('/api/checkout', {
+      method: 'POST',
+      body: JSON.stringify({ amount: cartTotal, customer, gateway }),
+    });
+    const order = await res.json();
+
+    // 2. Open popup modal or redirect
+    openPaymentModal({
+      order,
+      name: 'BoostStore',
+      description: 'Order Payment',
+      themeColor: '#4f46e5',
+      onSuccess: async (result) => {
+        router.push(`/order-success?id=${result.orderId}`);
+      },
+      onFailure: (err) => {
+        alert(`Payment failed: ${err.message}`);
+      },
+    });
+  };
+
+  return (
+    <div style={{ display: 'flex', gap: '10px' }}>
+      <button disabled={isProcessing} onClick={() => handlePay('cashfree')}>
+        Pay Online (UPI / Card)
+      </button>
+      <button disabled={isProcessing} onClick={() => handlePay('cod')}>
+        Cash on Delivery
+      </button>
+    </div>
+  );
 }
 ```
 
 ---
 
-### 5. Instant Refunds
+### Step 4: Next.js Universal Webhook Handler (`app/api/webhooks/[gateway]/route.ts`)
 
-```typescript
-const refund = await payments.refund({
-  gateway: 'razorpay',
-  paymentId: 'pay_456',
-  amount: 1499.00, // full or partial
-  reason: 'Customer cancelled before dispatch',
-});
+Verify webhook signatures in 2 lines with standard normalized events:
 
-console.log('Refund ID:', refund.refundId, 'Status:', refund.status);
+```typescript
+import { payments } from '@/lib/payments';
+
+export async function POST(
+  req: Request,
+  { params }: { params: { gateway: string } }
+) {
+  const result = await payments.verifyNextJsWebhook(req, {
+    gateway: params.gateway as any,
+  });
+
+  if (!result.isValid) {
+    return new Response('Invalid Signature', { status: 400 });
+  }
+
+  // Handle standardized events across all payment gateways!
+  switch (result.normalizedEvent) {
+    case 'PAYMENT_SUCCESS':
+      console.log(`✅ Order ${result.orderId} paid! Amount: ₹${result.amount}`);
+      // TODO: Update Order status to 'PAID' in database
+      break;
+
+    case 'PAYMENT_FAILED':
+      console.log(`❌ Order ${result.orderId} failed.`);
+      break;
+
+    case 'REFUND_PROCESSED':
+      console.log(`🔄 Refund completed for ${result.paymentId}`);
+      break;
+  }
+
+  return new Response('OK');
+}
 ```
 
 ---
 
-## 🛠️ CLI Quickstart
+## 🛠️ CLI Utilities
 
-Generate an environment template or check supported gateways:
+Test and configure payment credentials quickly:
 
 ```bash
-# List all 6 supported gateways
+# List supported gateways and their status
 npx @boostengine/payments list
 
-# Generate .env.payments.example template
+# Generate .env.payments template
 npx @boostengine/payments init-env
-
-# Compute quick SHA-256 hash
-npx @boostengine/payments hash "my_test_payload"
 ```
 
 ---
 
 ## 📄 License
-MIT © Boost Engine Team
+
+MIT © [Boost Engine](https://github.com/boostengine)

package/dist/index.cjs

@@ -178,6 +178,7 @@ var RazorpayAdapter = class extends BasePaymentAdapter {
       paymentId: payment.id,
       orderId: options.orderId,
       amount: payment.amount / 100,
+      // Normalized back to standard currency units
       currency: payment.currency,
       paymentMethod: payment.method,
       rawResponse: payment
@@ -202,6 +203,7 @@ var RazorpayAdapter = class extends BasePaymentAdapter {
       refundId: res.id,
       paymentId: options.paymentId,
       amount: res.amount / 100,
+      // Normalized to standard currency units
       status: res.status === "processed" ? "SUCCESS" : "PENDING",
       rawResponse: res
     };
@@ -211,32 +213,58 @@ var RazorpayAdapter = class extends BasePaymentAdapter {
     if (!secret) {
       return {
         isValid: false,
+        normalizedEvent: "UNKNOWN",
         gateway: "razorpay",
         error: "Razorpay webhookSecret is not configured."
       };
     }
     const signature = this.getHeader(options.headers, "x-razorpay-signature");
-    if (!signature || typeof signature !== "string") {
+    if (!signature) {
       return {
         isValid: false,
+        normalizedEvent: "UNKNOWN",
         gateway: "razorpay",
-        error: "Missing X-Razorpay-Signature header."
+        error: "Missing x-razorpay-signature header."
       };
     }
     const rawString = typeof options.rawBody === "string" ? options.rawBody : options.rawBody.toString("utf8");
     const expectedSignature = hmacSha256(rawString, secret);
     const isValid = safeCompare(expectedSignature, signature);
-    let parsedData;
+    let parsed;
     try {
-      parsedData = JSON.parse(rawString);
+      parsed = JSON.parse(rawString);
     } catch {
-      parsedData = null;
+      parsed = null;
     }
+    const rawEvent = parsed?.event || "";
+    let normalizedEvent = "UNKNOWN";
+    if (rawEvent === "order.paid" || rawEvent === "payment.captured" || rawEvent === "payment.authorized") {
+      normalizedEvent = "PAYMENT_SUCCESS";
+    } else if (rawEvent === "payment.failed") {
+      normalizedEvent = "PAYMENT_FAILED";
+    } else if (rawEvent === "refund.processed" || rawEvent === "refund.created") {
+      normalizedEvent = "REFUND_PROCESSED";
+    } else if (rawEvent === "refund.failed") {
+      normalizedEvent = "REFUND_FAILED";
+    } else if (rawEvent?.includes("dispute")) {
+      normalizedEvent = "DISPUTE_CREATED";
+    }
+    const paymentEntity = parsed?.payload?.payment?.entity;
+    const orderEntity = parsed?.payload?.order?.entity;
+    const orderId = orderEntity?.receipt || paymentEntity?.order_id || orderEntity?.id;
+    const paymentId = paymentEntity?.id;
+    const amount = paymentEntity?.amount ? paymentEntity.amount / 100 : orderEntity?.amount ? orderEntity.amount / 100 : void 0;
+    const currency = paymentEntity?.currency || orderEntity?.currency;
     return {
       isValid,
+      normalizedEvent,
+      rawEvent,
       gateway: "razorpay",
-      event: parsedData?.event,
-      data: parsedData?.payload
+      orderId,
+      paymentId,
+      amount,
+      currency,
+      data: parsed?.payload
     };
   }
 };
@@ -369,17 +397,41 @@ var CashfreeAdapter = class extends BasePaymentAdapter {
       ).toString("base64");
       isValid = safeCompare(expectedSignature, signature);
     }
-    let parsedData;
+    let parsed;
     try {
-      parsedData = JSON.parse(rawString);
+      parsed = JSON.parse(rawString);
     } catch {
-      parsedData = null;
+      parsed = null;
+    }
+    const rawEvent = parsed?.type || "";
+    let normalizedEvent = "UNKNOWN";
+    if (rawEvent === "PAYMENT_SUCCESS_WEBHOOK") {
+      normalizedEvent = "PAYMENT_SUCCESS";
+    } else if (rawEvent === "PAYMENT_FAILED_WEBHOOK" || rawEvent === "USER_DROPPED_WEBHOOK") {
+      normalizedEvent = "PAYMENT_FAILED";
+    } else if (rawEvent === "REFUND_STATUS_WEBHOOK") {
+      const refundStatus = parsed?.data?.refund?.refund_status;
+      normalizedEvent = refundStatus === "SUCCESS" ? "REFUND_PROCESSED" : "REFUND_FAILED";
+    } else if (rawEvent?.includes("DISPUTE")) {
+      normalizedEvent = "DISPUTE_CREATED";
     }
+    const orderData = parsed?.data?.order;
+    const paymentData = parsed?.data?.payment;
+    const refundData = parsed?.data?.refund;
+    const orderId = orderData?.order_id || refundData?.order_id;
+    const paymentId = paymentData ? String(paymentData.cf_payment_id) : refundData ? String(refundData.cf_payment_id) : void 0;
+    const amount = paymentData?.payment_amount ?? orderData?.order_amount ?? refundData?.refund_amount;
+    const currency = paymentData?.payment_currency || orderData?.order_currency;
     return {
       isValid,
+      normalizedEvent,
+      rawEvent,
       gateway: "cashfree",
-      event: parsedData?.type,
-      data: parsedData?.data
+      orderId,
+      paymentId,
+      amount,
+      currency,
+      data: parsed?.data
     };
   }
 };
@@ -505,17 +557,36 @@ var PhonePeAdapter = class extends BasePaymentAdapter {
     try {
       parsed = JSON.parse(rawString);
     } catch {
-      return { isValid: false, gateway: "phonepe", error: "Invalid JSON payload" };
+      return { isValid: false, normalizedEvent: "UNKNOWN", gateway: "phonepe", error: "Invalid JSON payload" };
     }
     if (!parsed.response) {
-      return { isValid: false, gateway: "phonepe", error: "Missing response field in PhonePe callback" };
+      return { isValid: false, normalizedEvent: "UNKNOWN", gateway: "phonepe", error: "Missing response field in PhonePe callback" };
+    }
+    let decoded = {};
+    try {
+      decoded = JSON.parse(base64Decode(parsed.response));
+    } catch {
+      return { isValid: false, normalizedEvent: "UNKNOWN", gateway: "phonepe", error: "Failed to decode base64 PhonePe response" };
     }
-    const decoded = JSON.parse(base64Decode(parsed.response));
-    decoded.code === "PAYMENT_SUCCESS";
+    const rawEvent = decoded.code || "";
+    let normalizedEvent = "UNKNOWN";
+    if (rawEvent === "PAYMENT_SUCCESS") {
+      normalizedEvent = "PAYMENT_SUCCESS";
+    } else if (rawEvent === "PAYMENT_ERROR" || rawEvent === "PAYMENT_DECLINED") {
+      normalizedEvent = "PAYMENT_FAILED";
+    }
+    const orderId = decoded.data?.merchantTransactionId;
+    const paymentId = decoded.data?.transactionId;
+    const amount = decoded.data?.amount ? decoded.data.amount / 100 : void 0;
     return {
       isValid: true,
+      normalizedEvent,
+      rawEvent,
       gateway: "phonepe",
-      event: decoded.code,
+      orderId,
+      paymentId,
+      amount,
+      currency: "INR",
       data: decoded.data
     };
   }
@@ -630,11 +701,21 @@ var PaytmAdapter = class extends BasePaymentAdapter {
       const params = new URLSearchParams(rawString);
       parsed = Object.fromEntries(params.entries());
     }
-    const isSuccess = parsed?.STATUS === "TXN_SUCCESS" || parsed?.resultInfo?.resultStatus === "TXN_SUCCESS";
+    const rawStatus = parsed?.STATUS || parsed?.resultInfo?.resultStatus;
+    const isSuccess = rawStatus === "TXN_SUCCESS";
+    const normalizedEvent = isSuccess ? "PAYMENT_SUCCESS" : "PAYMENT_FAILED";
+    const orderId = parsed?.ORDERID || parsed?.orderId;
+    const paymentId = parsed?.TXNID || parsed?.txnId;
+    const amount = parsed?.TXNAMOUNT ? parseFloat(parsed.TXNAMOUNT) : void 0;
     return {
       isValid: true,
+      normalizedEvent,
+      rawEvent: rawStatus,
       gateway: "paytm",
-      event: isSuccess ? "TXN_SUCCESS" : "TXN_FAILURE",
+      orderId,
+      paymentId,
+      amount,
+      currency: "INR",
       data: parsed
     };
   }
@@ -726,6 +807,7 @@ var StripeAdapter = class extends BasePaymentAdapter {
       refundId: res.id,
       paymentId: options.paymentId,
       amount: res.amount / 100,
+      // Normalized to standard currency units
       status: res.status === "succeeded" ? "SUCCESS" : "PENDING",
       rawResponse: res
     };
@@ -733,11 +815,11 @@ var StripeAdapter = class extends BasePaymentAdapter {
   async verifyWebhook(options) {
     const secret = options.webhookSecret || this.config.webhookSecret;
     if (!secret) {
-      return { isValid: false, gateway: "stripe", error: "Stripe webhookSecret is not configured." };
+      return { isValid: false, normalizedEvent: "UNKNOWN", gateway: "stripe", error: "Stripe webhookSecret is not configured." };
     }
     const sigHeader = this.getHeader(options.headers, "stripe-signature");
     if (!sigHeader || typeof sigHeader !== "string") {
-      return { isValid: false, gateway: "stripe", error: "Missing stripe-signature header." };
+      return { isValid: false, normalizedEvent: "UNKNOWN", gateway: "stripe", error: "Missing stripe-signature header." };
     }
     const parts = sigHeader.split(",");
     let timestamp = "";
@@ -757,11 +839,32 @@ var StripeAdapter = class extends BasePaymentAdapter {
     } catch {
       parsed = null;
     }
+    const rawEvent = parsed?.type || "";
+    let normalizedEvent = "UNKNOWN";
+    if (rawEvent === "checkout.session.completed" || rawEvent === "payment_intent.succeeded") {
+      normalizedEvent = "PAYMENT_SUCCESS";
+    } else if (rawEvent === "payment_intent.payment_failed") {
+      normalizedEvent = "PAYMENT_FAILED";
+    } else if (rawEvent === "charge.refunded") {
+      normalizedEvent = "REFUND_PROCESSED";
+    } else if (rawEvent?.includes("dispute")) {
+      normalizedEvent = "DISPUTE_CREATED";
+    }
+    const obj = parsed?.data?.object;
+    const orderId = obj?.client_reference_id || obj?.metadata?.order_id || obj?.id;
+    const paymentId = obj?.payment_intent || obj?.id;
+    const amount = obj?.amount_total ? obj.amount_total / 100 : obj?.amount ? obj.amount / 100 : void 0;
+    const currency = obj?.currency ? obj.currency.toUpperCase() : void 0;
     return {
       isValid,
+      normalizedEvent,
+      rawEvent,
       gateway: "stripe",
-      event: parsed?.type,
-      data: parsed?.data?.object
+      orderId,
+      paymentId,
+      amount,
+      currency,
+      data: obj
     };
   }
 };
@@ -830,8 +933,9 @@ var CODAdapter = class extends BasePaymentAdapter {
   async verifyWebhook(_options) {
     return {
       isValid: true,
+      normalizedEvent: "PAYMENT_SUCCESS",
+      rawEvent: "COD_ORDER",
       gateway: "cod",
-      event: "COD_ORDER",
       data: {}
     };
   }
@@ -962,6 +1066,60 @@ var PaymentManager = class {
     const adapter = this.getAdapter(options.gateway);
     return adapter.verifyWebhook(options);
   }
+  /**
+   * Ready-made Next.js 13/14/15 App Router Route Handler Webhook Authenticator.
+   * Directly consumes the standard web Request object with raw stream body handling:
+   *
+   * ```typescript
+   * export async function POST(req: Request) {
+   *   const result = await payments.verifyNextJsWebhook(req, { gateway: 'razorpay' });
+   *   if (!result.isValid) return new Response('Invalid Signature', { status: 400 });
+   *   console.log('Event:', result.normalizedEvent, result.orderId);
+   *   return new Response('OK');
+   * }
+   * ```
+   */
+  async verifyNextJsWebhook(request, options) {
+    try {
+      let rawBody = "";
+      if (typeof request.text === "function") {
+        rawBody = await request.text();
+      } else if (typeof request.body === "string") {
+        rawBody = request.body;
+      } else if (Buffer.isBuffer(request.body)) {
+        rawBody = request.body.toString("utf8");
+      }
+      const headers = {};
+      if (request.headers) {
+        if (typeof request.headers.forEach === "function") {
+          request.headers.forEach((val, key) => {
+            headers[key.toLowerCase()] = val;
+          });
+        } else if (typeof request.headers.entries === "function") {
+          for (const [key, val] of request.headers.entries()) {
+            headers[key.toLowerCase()] = val;
+          }
+        } else if (typeof request.headers === "object") {
+          Object.entries(request.headers).forEach(([k, v]) => {
+            headers[k.toLowerCase()] = Array.isArray(v) ? v[0] : v;
+          });
+        }
+      }
+      return this.verifyWebhook({
+        gateway: options.gateway,
+        rawBody,
+        headers,
+        webhookSecret: options.webhookSecret
+      });
+    } catch (err) {
+      return {
+        isValid: false,
+        normalizedEvent: "UNKNOWN",
+        gateway: options.gateway,
+        error: `Failed to process Next.js webhook: ${err.message}`
+      };
+    }
+  }
 };
 function createPaymentManager(options) {
   return new PaymentManager(options);