react-nomba-checkout-sdk 2.0.2 → 2.0.6

package/README.md

@@ -1,6 +1,6 @@
 # 🚀 React Nomba Checkout SDK
 
-The **`react-nomba-checkout-sdk`** is a lightweight React SDK designed to simplify payment processing and checkout integration using [Nomba's](https://nomba.com/) secure and reliable infrastructure.
+The **react-nomba-checkout-sdk** is a lightweight React SDK designed to simplify payment processing and checkout integration using [Nomba's](https://nomba.com/) secure and reliable infrastructure.
 
 > Built with ❤️ by **Israel Itua**
 
@@ -18,15 +18,15 @@ yarn add react-nomba-checkout-sdk
 
 ---
 
-## ⚡ Quick Start
+## ⚡ Quick Start (React)
 
-Here’s how to integrate the SDK into your React project:
+Here's how to integrate the SDK into your React project:
 
 ```jsx
 import { useState } from 'react';
 import {
-  useNombaCheckout,
-  InitializeNombaCheckout,
+	useNombaCheckout,
+	InitializeNombaCheckout,
 } from 'react-nomba-checkout-sdk';
 import './App.css';
 
@@ -34,59 +34,62 @@ import './App.css';
 InitializeNombaCheckout();
 
 function App() {
-  const [isLoading, setIsLoading] = useState(false);
-
-  const handleCheckout = async () => {
-    setIsLoading(true);
-
-    const res = await useNombaCheckout({
-      accountId: 'your-account-id',
-      clientId: 'your-client-id',
-      order: {
-        callbackUrl: 'sample-url',
-        customerEmail: 'sample-email@gmail.com',
-        amount: '10.00',
-        currency: 'NGN',
-        splitRequest: {
-          splitType: 'PERCENTAGE',
-          splitList: [
-            {
-              accountId: 'your-account-id',
-              value: '65.45',
-            },
-          ],
-        },
-      },
-      tokenizeCard: 'true',
-      onCreateOrder: (orderReference) => {
-        console.log('Function called after the order is created');
-        console.log({ orderReference });
-        setIsLoading(false);
-      },
-      onFailure: (err) => {
-        console.log('Function called if error occurs while creating order.');
-        console.log(err);
-        setIsLoading(false);
-      },
-      onClose: () => {
-        console.log('Function called when modal is closed.');
-        setIsLoading(false);
-      },
-      onPaymentSuccess: (successResponse) => {
-        console.log('Function called on payment success.');
-        console.log({ successResponse });
-      },
-    });
-  };
-
-  return (
-    <>
-      <h1>Pay with Nomba</h1>
-      <button onClick={handleCheckout}>
-        {isLoading ? 'Please wait...' : 'Pay with Nomba Checkout'}
-      </button>
-    </>
-  );
+	const [isLoading, setIsLoading] = useState(false);
+
+	const handleCheckout = async () => {
+		setIsLoading(true);
+
+		const res = await useNombaCheckout({
+			accountId: 'your-account-id',
+			clientId: 'your-client-id',
+			order: {
+				callbackUrl: 'sample-url',
+				customerEmail: 'sample-email@gmail.com',
+				amount: '10.00',
+				currency: 'NGN',
+				orderMetaData: {
+					customMerchant: 'true',
+				},
+				splitRequest: {
+					splitType: 'PERCENTAGE',
+					splitList: [
+						{
+							accountId: 'your-account-id',
+							value: '65.45',
+						},
+					],
+				},
+			},
+			tokenizeCard: 'true',
+			onCreateOrder: (orderReference) => {
+				console.log('Function called after the order is created');
+				console.log({ orderReference });
+				setIsLoading(false);
+			},
+			onFailure: (err) => {
+				console.log('Function called if error occurs while creating order.');
+				console.log(err);
+				setIsLoading(false);
+			},
+			onClose: () => {
+				console.log('Function called when modal is closed.');
+				setIsLoading(false);
+			},
+			onPaymentSuccess: (successResponse) => {
+				console.log('Function called on payment success.');
+				console.log({ successResponse });
+			},
+		});
+	};
+
+	return (
+		<>
+			<h1>Pay with Nomba</h1>
+			<button onClick={handleCheckout}>
+				{isLoading ? 'Please wait...' : 'Pay with Nomba Checkout'}
+			</button>
+		</>
+	);
 }
 
 export default App;
@@ -94,17 +97,297 @@ export default App;
 
 ---
 
+## 🔥 Next.js Integration (App Router)
+
+For Next.js 13+ with App Router, follow this setup to ensure proper client-side rendering:
+
+### Step 1: Create the Checkout Component
+
+Create `components/NombaCheckoutButton.tsx`:
+
+```tsx
+'use client';
+
+import { useState, useEffect } from 'react';
+import {
+	useNombaCheckout,
+	InitializeNombaCheckout,
+} from 'react-nomba-checkout-sdk';
+
+export default function NombaCheckoutButton() {
+	const [isLoading, setIsLoading] = useState(false);
+	const [isInitialized, setIsInitialized] = useState(false);
+
+	useEffect(() => {
+		InitializeNombaCheckout();
+		setIsInitialized(true);
+	}, []);
+
+	const handleCheckout = async () => {
+		if (!isInitialized) {
+			console.log('SDK not initialized yet');
+			return;
+		}
+
+		setIsLoading(true);
+
+		const res = await useNombaCheckout({
+			accountId: 'your-account-id',
+			clientId: 'your-client-id',
+			order: {
+				callbackUrl: 'https://your-callback-url.com',
+				customerEmail: 'sample-email@gmail.com',
+				amount: '10.00',
+				currency: 'NGN',
+				orderMetaData: {
+					customMerchant: 'true',
+				},
+				splitRequest: {
+					splitType: 'PERCENTAGE',
+					splitList: [
+						{
+							accountId: 'your-account-id',
+							value: 65.45,
+						},
+					],
+				},
+				orderReference: 'your-order-reference',
+				customerId: '',
+				accountId: 'your-account-id',
+			},
+			tokenizeCard: true,
+			onCreateOrder: (orderReference) => {
+				console.log('Function called after the order is created');
+				console.log({ orderReference });
+				setIsLoading(false);
+			},
+			onFailure: (err) => {
+				console.log('Function called if error occurs while creating order.');
+				console.log(err);
+				setIsLoading(false);
+			},
+			onClose: () => {
+				console.log('Function called when modal is closed.');
+				setIsLoading(false);
+				return {};
+			},
+			onPaymentSuccess: (successResponse) => {
+				console.log('Function called on payment success.');
+				console.log({ successResponse });
+				return {};
+			},
+		});
+	};
+
+	return (
+		<>
+			<h1>Pay with Nomba</h1>
+			<button onClick={handleCheckout} disabled={!isInitialized}>
+				{isLoading ? 'Please wait...' : 'Pay with Nomba Checkout'}
+			</button>
+		</>
+	);
+}
+```
+
+### Step 2: Use Dynamic Import in Your Page
+
+Create or update your `app/page.tsx`:
+
+```tsx
+'use client';
+
+import dynamic from 'next/dynamic';
+
+// Dynamically import the component with SSR disabled
+const NombaCheckoutButton = dynamic(
+	() => import('@/components/NombaCheckoutButton'),
+	{ ssr: false }
+);
+
+export default function Home() {
+	return <NombaCheckoutButton />;
+}
+```
+
+### Step 3: Configure Layout (Optional)
+
+Update your `app/layout.tsx` if needed:
+
+```tsx
+import type { Metadata } from 'next';
+import { Geist, Geist_Mono } from 'next/font/google';
+import './globals.css';
+
+const geistSans = Geist({
+	variable: '--font-geist-sans',
+	subsets: ['latin'],
+});
+
+const geistMono = Geist_Mono({
+	variable: '--font-geist-mono',
+	subsets: ['latin'],
+});
+
+export const metadata: Metadata = {
+	title: 'Nomba Checkout Integration',
+	description: 'Payment processing with Nomba',
+};
+
+export default function RootLayout({
+	children,
+}: Readonly<{
+	children: React.ReactNode;
+}>) {
+	return (
+		<html lang='en'>
+			<body
+				className={`${geistSans.variable} ${geistMono.variable} antialiased`}
+				suppressHydrationWarning
+			>
+				{children}
+			</body>
+		</html>
+	);
+}
+```
+
+### ⚠️ Important Next.js Notes
+
+- **Always use dynamic import with `ssr: false`** - The SDK requires browser APIs and must be rendered client-side only
+- **Initialize SDK in useEffect** - Ensures proper initialization after component mounts
+- **Use 'use client' directive** - Required for components using browser-specific features
+- **Check initialization state** - Prevent checkout calls before SDK is ready
+
+---
+
 ## 🔍 API Reference
 
-### `InitializeNombaCheckout()`
+### InitializeNombaCheckout()
+
+Initializes the SDK. Call once when your app loads (or in useEffect for Next.js).
+
+```js
+InitializeNombaCheckout();
+```
+
+---
+
+### useNombaCheckout(options)
+
+Launches the Nomba checkout modal.
+
+#### Options
 
-Initializes the SDK. Call once when your app loads.
+| Parameter          | Type           | Required | Description                    |
+| ------------------ | -------------- | -------- | ------------------------------ |
+| `accountId`        | string         | Yes      | Your Nomba account ID          |
+| `clientId`         | string         | Yes      | Your Nomba client ID           |
+| `order`            | object         | Yes      | Order details (see below)      |
+| `tokenizeCard`     | boolean/string | No       | Enable card tokenization       |
+| `onCreateOrder`    | function       | No       | Callback after order creation  |
+| `onFailure`        | function       | No       | Callback on error              |
+| `onClose`          | function       | No       | Callback when modal closes     |
+| `onPaymentSuccess` | function       | No       | Callback on successful payment |
+
+#### Order Object
+
+| Field            | Type   | Required | Description                 |
+| ---------------- | ------ | -------- | --------------------------- |
+| `callbackUrl`    | string | Yes      | URL for payment callback    |
+| `customerEmail`  | string | Yes      | Customer's email address    |
+| `amount`         | string | Yes      | Payment amount              |
+| `currency`       | string | Yes      | Currency code (e.g., 'NGN') |
+| `orderReference` | string | No       | Your order reference        |
+| `customerId`     | string | No       | Customer identifier         |
+| `accountId`      | string | No       | Account ID for the order    |
+| `orderMetaData`  | object | No       | Additional metadata         |
+| `splitRequest`   | object | No       | Payment split configuration |
+
+#### Split Request Object
+
+| Field       | Type   | Required | Description                   |
+| ----------- | ------ | -------- | ----------------------------- |
+| `splitType` | string | Yes      | 'PERCENTAGE' or 'FLAT'        |
+| `splitList` | array  | Yes      | Array of split configurations |
+
+#### Split List Item
+
+| Field       | Type          | Required | Description                 |
+| ----------- | ------------- | -------- | --------------------------- |
+| `accountId` | string        | Yes      | Account ID to receive split |
+| `value`     | number/string | Yes      | Split amount or percentage  |
 
 ---
 
-### `useNombaCheckout(options)`
+## 📝 Example with All Options
 
-Launches the Nomba checkout modal. |
+```jsx
+const res = await useNombaCheckout({
+	accountId: 'acc_123456',
+	clientId: 'client_123456',
+	order: {
+		callbackUrl: 'https://yoursite.com/payment/callback',
+		customerEmail: 'customer@example.com',
+		amount: '5000.00',
+		currency: 'NGN',
+		orderReference: 'ORDER-2024-001',
+		customerId: 'CUST-001',
+		accountId: 'acc_123456',
+		orderMetaData: {
+			customMerchant: 'true',
+			productName: 'Premium Plan',
+		},
+		splitRequest: {
+			splitType: 'PERCENTAGE',
+			splitList: [
+				{
+					accountId: 'acc_partner_1',
+					value: 20,
+				},
+				{
+					accountId: 'acc_partner_2',
+					value: 15,
+				},
+			],
+		},
+	},
+	tokenizeCard: true,
+	onCreateOrder: (orderReference) => {
+		console.log('Order created:', orderReference);
+	},
+	onFailure: (error) => {
+		console.error('Payment failed:', error);
+	},
+	onClose: () => {
+		console.log('Checkout modal closed');
+		return {};
+	},
+	onPaymentSuccess: (response) => {
+		console.log('Payment successful:', response);
+		return {};
+	},
+});
+```
+
+---
+
+## 🛠️ Troubleshooting
+
+### Next.js Hydration Errors
+
+- Ensure you're using `dynamic` import with `ssr: false`
+- Add `suppressHydrationWarning` to your body tag in layout.tsx
+
+### SDK Not Initialized
+
+- In Next.js, initialize the SDK in `useEffect`
+- Check that the button is disabled until `isInitialized` is true
+
+### Modal Not Opening
+
+- Verify that `InitializeNombaCheckout()` was called before `useNombaCheckout()`
+- Check browser console for errors
 
 ---
 
@@ -112,4 +395,23 @@ Launches the Nomba checkout modal. |
 
 **Israel Itua**  
 Frontend Engineer  
-[GitHub](https://github.com/the-israelItua/) •
+[GitHub](https://github.com/the-israelItua/)
+
+---
+
+## 👥 Contributors
+
+- **Israel Itua** - Original Author - [GitHub](https://github.com/the-israelItua/)
+- **Kelechi Uma** - Contributor - [GitHub](https://github.com/Kusjay)
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome!

package/dist/apis/useNombaCheckout.d.ts

@@ -16,6 +16,9 @@ interface CheckoutPayload {
                 }
             ];
         };
+        orderMetaData?: {
+            [key: string]: any;
+        };
     };
     tokenizeCard: boolean;
     clientId: string;

package/dist/index.esm.js

@@ -4042,6 +4042,7 @@ var useNombaCheckout = function (payload) { return __awaiter(undefined, undefine
         switch (_d.label) {
             case 0:
                 _d.trys.push([0, 2, , 3]);
+                console.log('🔗 Using LOCAL SDK version!', payload.order.orderMetaData);
                 return [4 /*yield*/, handleNombaApiCall('/checkout/order', 'POST', {
                         order: __assign(__assign({}, payload.order), { accountId: payload.accountId }),
                         tokenizeCard: payload.tokenizeCard,