@enomshop/paystack 0.0.1

package/README.md

@@ -0,0 +1,197 @@
+# Medusa v2 Paystack Payment Plugin
+
+A robust, production-ready Paystack payment integration for **MedusaJS v2**. This plugin not only handles standard checkouts but also introduces advanced features like partial payments, an admin payment history widget, and a failsafe cron job for missed webhooks.
+
+## ✨ Features
+
+- **Full Medusa v2 Compliance:** Uses the new isolated modules, file-based routing, and Admin SDK.
+- **Standard Checkout:** Seamlessly process payments during the standard Medusa checkout flow.
+- **Partial Payments / Installments:** Includes a custom storefront API route to allow customers to pay off an order in multiple installments. Works perfectly for both registered users and **Guest Customers** (automatically falls back to the original order email).
+- **Admin Dashboard (Payments > Paystack):** 
+  - **Live Account Balance:** Displays your live Paystack account balance and all-time total received directly from the Paystack API.
+  - **Revenue Graph:** A beautiful bar chart visualizing your captured revenue over time.
+  - **Endless Scroll History:** View your entire Paystack payment history directly in Medusa. Simply scroll to the bottom of the table to automatically load the next batch of payments.
+  - **Search:** Instantly search for a specific transaction using a Medusa Order ID (e.g., `1234`) or a Paystack Transaction Reference.
+- **Failsafe Cron Job:** A scheduled job runs every 15 minutes to verify and capture pending payments in case Paystack webhooks are missed or delayed. Includes rate-limiting and race-condition prevention.
+- **Currency Validation:** Fails fast if a customer attempts to checkout using a currency not supported by Paystack.
+- **Secure Webhooks:** Verifies Paystack webhook signatures using HMAC SHA512.
+
+---
+
+## 🚀 1. Backend Installation & Integration
+
+### Step 1: Add the Plugin Files
+Ensure all the provided files are placed in your Medusa v2 backend `src` directory:
+- `src/services/paystack-payment-processor.ts`
+- `src/lib/paystack.ts`
+- `src/utils/currencyCode.ts`
+- `src/api/store/orders/[id]/paystack-payment/route.ts`
+- `src/admin/widgets/payment-history-widget.tsx`
+- `src/jobs/sync-paystack-payments.ts`
+
+### Step 2: Environment Variables
+Add your Paystack Secret Key to your backend `.env` file:
+```env
+PAYSTACK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### Step 3: Register the Payment Provider
+Update your `medusa-config.ts` to register the Paystack payment provider in the Payment Module:
+
+```typescript
+import { loadEnv, defineConfig } from "@medusajs/framework/utils"
+
+loadEnv(process.env.NODE_ENV || "development", process.cwd())
+
+module.exports = defineConfig({
+  projectConfig: {
+    databaseUrl: process.env.DATABASE_URL,
+    http: {
+      storeCors: process.env.STORE_CORS!,
+      adminCors: process.env.ADMIN_CORS!,
+      authCors: process.env.AUTH_CORS!,
+      jwtSecret: process.env.JWT_SECRET || "supersecret",
+      cookieSecret: process.env.COOKIE_SECRET || "supersecret",
+    },
+  },
+  modules: [
+    {
+      resolve: "@medusajs/payment",
+      options: {
+        providers: [
+          {
+            resolve: "./src/services/paystack-payment-processor",
+            id: "paystack",
+            options: {
+              secret_key: process.env.PAYSTACK_SECRET_KEY,
+              debug: process.env.NODE_ENV !== "production",
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+### Step 4: Configure Webhooks in Paystack
+Log in to your Paystack Dashboard, go to **Settings > API Keys & Webhooks**, and set your webhook URL to:
+```text
+https://<YOUR_MEDUSA_BACKEND_URL>/hooks/payment/paystack
+```
+*Note: Medusa v2 automatically routes webhooks to the provider based on the ID (`paystack`).*
+
+---
+
+## 💻 2. Storefront Implementation (Next.js / Fresh.js)
+
+You can use this plugin in two ways on your storefront: for standard checkout, and for partial payments on an existing order.
+
+### Scenario A: Standard Checkout Flow
+During a standard checkout, you initialize the payment session using the Medusa JS Client.
+
+```javascript
+// Example in Next.js or Fresh.js
+import { medusaClient } from "@lib/config"; // Your Medusa JS Client instance
+
+const handleStandardCheckout = async (cartId, email) => {
+  // 1. Initialize payment sessions for the cart
+  await medusaClient.carts.createPaymentSessions(cartId);
+
+  // 2. Select Paystack as the payment session
+  const { cart } = await medusaClient.carts.setPaymentSession(cartId, {
+    provider_id: "paystack",
+  });
+
+  // 3. Get the Paystack authorization URL from the session data
+  const paystackSession = cart.payment_collection.payment_sessions.find(
+    (s) => s.provider_id === "paystack"
+  );
+  
+  const authUrl = paystackSession.data.paystackTxAuthorizationUrl;
+
+  // 4. Redirect the user to Paystack to complete payment
+  window.location.href = authUrl;
+};
+```
+
+### Scenario B: Partial Payments / Installments
+If an order already exists and the customer wants to pay a portion of the remaining balance, use the custom API route we created.
+
+```javascript
+// Example in Next.js or Fresh.js (e.g., on an Order Details page)
+import { useState } from "react";
+
+export default function PartialPaymentButton({ orderId, remainingBalance, customerEmail }) {
+  const [amountToPay, setAmountToPay] = useState(0);
+  const [loading, setLoading] = useState(false);
+
+  const handlePartialPayment = async () => {
+    if (amountToPay <= 0 || amountToPay > remainingBalance) {
+      alert("Invalid amount");
+      return;
+    }
+
+    setLoading(true);
+    try {
+      // Call the custom Medusa backend API route
+      const response = await fetch(`${process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL}/store/orders/${orderId}/paystack-payment`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          amount: amountToPay,
+          email: customerEmail,
+          callback_url: `${window.location.origin}/order/${orderId}/success`, // Redirect back here after payment
+          metadata: {
+            note: "Partial installment payment",
+          }
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.message);
+      }
+
+      const { payment_session } = await response.json();
+
+      // Redirect the user to Paystack
+      window.location.href = payment_session.data.paystackTxAuthorizationUrl;
+    } catch (err) {
+      console.error(err);
+      alert("Failed to initiate payment: " + err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div>
+      <h3>Remaining Balance: {remainingBalance}</h3>
+      <input 
+        type="number" 
+        value={amountToPay} 
+        onChange={(e) => setAmountToPay(Number(e.target.value))} 
+        max={remainingBalance}
+      />
+      <button onClick={handlePartialPayment} disabled={loading}>
+        {loading ? "Processing..." : "Pay Installment"}
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+## 🛡️ 3. Production Readiness Features Explained
+
+1. **Amount Handling:** Medusa stores amounts in the lowest denomination (e.g., cents/kobo). The plugin safely passes this exact value to Paystack (`Math.round(Number(amount))`) without dangerous multipliers, preventing accidental overcharging.
+2. **Cron Job Failsafe (`src/jobs/sync-paystack-payments.ts`):** 
+   - Runs every 15 minutes.
+   - Only checks payments older than 15 minutes to prevent race conditions with incoming webhooks.
+   - Includes a `200ms` sleep delay between API calls to prevent hitting Paystack's rate limits (`429 Too Many Requests`) if you have a large backlog of abandoned checkouts.
+3. **Currency Validation:** The processor checks if the cart's currency is supported by Paystack (`NGN`, `GHS`, `ZAR`, `USD`, `KES`, `EGP`, `RWF`) *before* making an API call, failing fast and returning a clean error to the storefront.
+4. **Overpayment Prevention:** The partial payment API route calculates the total captured amount of all previous payments. If a customer tries to pay more than the remaining balance, the API rejects the request.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@enomshop/paystack",
+  "version": "0.0.1",
+  "description": "Medusa v2 plugin for Paystack payment provider",
+  "author": "Enomshop",
+  "license": "MIT",
+  "files": [
+    ".medusa/server",
+    "!.medusa/server/**/*.ts",
+    "!.medusa/server/**/*.tsbuildinfo"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./workflows": "./.medusa/server/src/workflows/index.js",
+    "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./providers/*": "./.medusa/server/src/providers/*/index.js",
+    "./*": "./.medusa/server/src/*.js",
+    "./admin": {
+      "import": "./.medusa/server/src/admin/index.mjs",
+      "require": "./.medusa/server/src/admin/index.js",
+      "default": "./.medusa/server/src/admin/index.js"
+    }
+  },
+  "keywords": [
+    "medusa",
+    "plugin",
+    "medusa-plugin-other",
+    "medusa-plugin",
+    "medusa-v2"
+  ],
+  "scripts": {
+    "build": "medusa plugin:build && find .medusa/server -name '*.ts' -delete",
+    "dev": "medusa plugin:develop",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "recharts": "^3.8.0"
+  },
+  "devDependencies": {
+    "@medusajs/admin-sdk": "2.12.4",
+    "@medusajs/cli": "2.12.4",
+    "@medusajs/framework": "2.12.4",
+    "@medusajs/icons": "2.12.4",
+    "@medusajs/medusa": "2.12.4",
+    "@medusajs/test-utils": "2.12.4",
+    "@medusajs/ui": "4.0.25",
+    "@swc/core": "^1.7.28",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.2",
+    "@types/react-dom": "^18.2.25",
+    "prop-types": "^15.8.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.2",
+    "vite": "^5.2.11",
+    "yalc": "^1.0.0-pre.53"
+  },
+  "peerDependencies": {
+    "@medusajs/admin-sdk": "2.12.4",
+    "@medusajs/cli": "2.12.4",
+    "@medusajs/framework": "2.12.4",
+    "@medusajs/icons": "2.12.4",
+    "@medusajs/medusa": "2.12.4",
+    "@medusajs/test-utils": "2.12.4",
+    "@medusajs/ui": "4.0.25"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "yarn@4.12.0"
+}