@payloqa/payment-widget 1.0.0 → 1.0.1

package/README.md

@@ -1,198 +1,208 @@
 # 💳 Payloqa Payment Widget
 
-A secure React payment processing widget for handling transactions with multiple payment methods.
+A React payment widget for processing mobile money payments. Easily integrate secure payment processing into your React applications.
 
 ## ✨ Features
 
-- 💳 **Multiple Payment Methods** - Credit cards, mobile money, bank transfers
-- 🔒 **Secure Processing** - PCI-compliant payment handling
-- 📱 **Responsive Design** - Works on desktop, tablet, and mobile
-- 🎨 **Customizable UI** - Easy to style and brand
-- 📊 **Real-time Validation** - Instant payment method validation
-- 🔄 **Transaction Status** - Real-time payment status updates
-- 🧪 **HTML Testing** - Comprehensive test interface
-- 📦 **Multiple Builds** - UMD, ESM, and TypeScript declarations
+- 📱 Mobile money payment processing (MTN, Telecel, AirtelTigo)
+- 🔐 OTP verification for secure transactions
+- 📱 Fully responsive design
+- 🎨 Customizable branding with primary color
+- ⚡ Easy integration with React
+- 🔄 Real-time payment status updates
+- ⏱️ Automatic timeout handling
 
-## 🚀 Quick Start
+## 🚀 Getting Started
 
-### Installation
+### 1. Get Your API Credentials
+
+Visit [https://developer.payloqa.com/](https://developer.payloqa.com/) to:
+
+- Create an account
+- Go to the **API Keys** page
+- Request payment access by filling out the KYC form
+- Once approved, you'll be notified and can access:
+  - Your **API Key**
+  - Your **Platform ID**
+
+### 2. Install the Package
 
 ```bash
 npm install @payloqa/payment-widget
 ```
 
-### Basic Usage
+### 3. Import and Use
 
 ```jsx
-import { PaymentWidget } from '@payloqa/payment-widget';
+import { PaymentWidget } from "@payloqa/payment-widget";
+import "@payloqa/payment-widget/dist/payment-widget.css";
 
 function App() {
+  const [isOpen, setIsOpen] = useState(false);
+
   const config = {
-    apiKey: 'your-api-key',
-    platformId: 'your-platform-id',
-    apiUrl: 'https://api.payloqa.com/v1/payments'
+    apiKey: "your-api-key",
+    platformId: "your-platform-id",
+    amount: 10.00,
+    currency: "GHS", // Optional, defaults to "GHS"
+    primaryColor: "#3B82F6", // Optional, your brand color
+    displayMode: "modal", // "modal" | "inline" | "fullpage"
+    redirect_url: "https://yoursite.com/callback", // Required
+    webhookUrl: "https://yoursite.com/webhook", // Required
+    orderId: "order-123", // Optional
+    metadata: { // Optional
+      customField: "value",
+    },
   };
 
-  const handleSuccess = (transaction) => {
-    console.log('Payment successful:', transaction);
-    console.log('Transaction ID:', transaction.id);
-    console.log('Amount:', transaction.amount);
+  const handleSuccess = (payment) => {
+    console.log("Payment successful!", payment);
+    console.log("Payment ID:", payment.payment_id);
+    console.log("Status:", payment.status);
+    console.log("Amount:", payment.amount);
   };
 
   const handleError = (error) => {
-    console.error('Payment failed:', error);
-  };
-
-  const handleStatusChange = (status) => {
-    console.log('Payment status:', status);
+    console.error("Payment failed:", error.message);
+    alert(`Error: ${error.message}`);
   };
 
   return (
-    <PaymentWidget
-      config={config}
-      amount={1000} // Amount in cents
-      currency="USD"
-      onSuccess={handleSuccess}
-      onError={handleError}
-      onStatusChange={handleStatusChange}
-    />
+    <div>
+      <button onClick={() => setIsOpen(true)}>Pay Now</button>
+      
+      <PaymentWidget
+        config={config}
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        onSuccess={handleSuccess}
+        onError={handleError}
+      />
+    </div>
   );
 }
 ```
 
 ## ⚙️ Configuration
 
-### PaymentWidgetConfig
+### Required Configuration
 
 ```typescript
 interface PaymentWidgetConfig {
-  apiKey: string;      // Your Payloqa API key
-  platformId: string;  // Your platform identifier
-  apiUrl: string;      // Payloqa payments API URL
+  apiKey: string;        // Your Payloqa API key
+  platformId: string;   // Your platform ID
+  amount: number;        // Payment amount (e.g., 10.00)
+  currency?: string;    // Currency code (default: "GHS")
+  displayMode?: string; // "modal" | "inline" | "fullpage" (default: "modal")
+  primaryColor?: string; // Your brand color in hex (e.g., "#3B82F6")
+  logoUrl?: string;     // Optional logo URL to display in header
+  redirect_url: string; // Required: HTTPS URL for redirect after payment
+  webhookUrl: string;   // Required: Webhook URL for server notifications
+  orderId?: string;     // Optional order identifier
+  metadata?: object;    // Optional metadata object
+  onSuccess?: (payment: PaymentData) => void;
+  onError?: (error: PaymentError) => void;
+}
+```
+
+### PaymentWidget Props
+
+```typescript
+interface PaymentWidgetProps {
+  config: PaymentWidgetConfig;
+  isOpen: boolean;      // Controls widget visibility
+  onClose?: () => void; // Called when widget is closed
 }
 ```
 
 ### Callbacks
 
 ```typescript
-// Success callback
-onSuccess: (transaction: PaymentTransaction) => void
+// Success callback - called when payment succeeds
+onSuccess: (payment: PaymentData) => void
 
-// Error callback
+// Error callback - called when payment fails
 onError: (error: PaymentError) => void
 
-// Status change callback
-onStatusChange: (status: PaymentStatus) => void
+// Close callback - called when widget is closed
+onClose: () => void
 ```
 
-## 🎨 Styling
-
-The widget uses Tailwind CSS for styling. You can customize the appearance:
-
-```css
-/* Custom styles */
-.payloqa-payment-widget {
-  --primary-color: #3b82f6;
-  --error-color: #ef4444;
-  --success-color: #10b981;
-}
-
-/* Override specific components */
-.payment-widget-container {
-  @apply bg-white rounded-lg shadow-lg p-6;
-}
+## 📱 Display Modes
 
-.payment-method-selector {
-  @apply border-2 border-gray-300 rounded-lg p-4;
-}
+The widget supports three display modes:
 
-.payment-form {
-  @apply space-y-4;
-}
+### Modal (Default)
+```jsx
+<PaymentWidget
+  config={{ ...config, displayMode: "modal" }}
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+/>
 ```
+Displays as a centered modal overlay with backdrop.
 
-## 🧪 Testing
+### Inline
+```jsx
+<PaymentWidget
+  config={{ ...config, displayMode: "inline" }}
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+/>
+```
+Displays inline within your page layout.
 
-### HTML Test Interface
+### Fullpage
+```jsx
+<PaymentWidget
+  config={{ ...config, displayMode: "fullpage" }}
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+/>
+```
+Displays as a full-page experience.
 
-The widget includes a comprehensive HTML test file:
+## 💳 Supported Networks
 
-```bash
-# Open the test interface
-open test.html
-```
+The widget supports mobile money payments for:
 
-**Test Features:**
-- ✅ Widget loading and mounting
-- ✅ Payment method selection
-- ✅ Form validation testing
-- ✅ Transaction processing simulation
-- ✅ Mobile responsiveness testing
-- ✅ Error scenario simulation
-- ✅ Real-time logging
+- **MTN** - MTN Mobile Money
+- **Telecel** - Telecel Cash (formerly Vodafone)
+- **AirtelTigo** - AirtelTigo Money
 
-### Framework Testing
+## 🔄 Payment Flow
 
-Test the widget in different React frameworks:
+1. **Phone Input** - User enters phone number and selects network
+2. **OTP Verification** - User receives and enters 4-digit OTP code
+3. **Processing** - Payment is processed and status is polled
+4. **Completion** - Success or error screen is shown
 
-```bash
-# Next.js
-npx create-next-app@latest my-app
-cd my-app
-npm install @payloqa/payment-widget
+## 📝 Sample Responses
 
-# Create React App
-npx create-react-app my-app
-cd my-app
-npm install @payloqa/payment-widget
+### Success Response
 
-# Vite
-npm create vite@latest my-app -- --template react-ts
-cd my-app
-npm install @payloqa/payment-widget
+```typescript
+{
+  payment_id: "pay_abc123",
+  status: "completed",
+  amount: 10.00,
+  currency: "GHS",
+  payment_method: "mobile_money",
+  phone_number: "+233XXXXXXXXX",
+  network: "mtn",
+  created_at: "2024-01-24T12:00:00Z",
+  updated_at: "2024-01-24T12:01:00Z",
+  paid_at: "2024-01-24T12:01:00Z"
+}
 ```
 
-## 📦 Build Outputs
-
-The widget is built for multiple formats:
-
-- **UMD** (`dist/index.umd.js`) - For direct browser use
-- **ESM** (`dist/index.esm.js`) - For modern bundlers
-- **TypeScript** (`dist/index.d.ts`) - Type definitions
-
-### Browser Usage
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <link rel="stylesheet" href="https://unpkg.com/@payloqa/payment-widget/dist/styles.css">
-</head>
-<body>
-  <div id="payment-widget"></div>
-  
-  <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
-  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
-  <script src="https://unpkg.com/@payloqa/payment-widget/dist/index.umd.js"></script>
-  
-  <script>
-    const config = {
-      apiKey: 'your-api-key',
-      platformId: 'your-platform-id',
-      apiUrl: 'https://api.payloqa.com/v1/payments'
-    };
-
-    const root = ReactDOM.createRoot(document.getElementById('payment-widget'));
-    root.render(React.createElement(PayloqaPaymentWidget.PaymentWidget, {
-      config: config,
-      amount: 1000,
-      currency: 'USD',
-      onSuccess: (transaction) => console.log('Success:', transaction),
-      onError: (error) => console.error('Error:', error)
-    }));
-  </script>
-</body>
-</html>
+### Error Response
+
+```typescript
+{
+  message: "Invalid OTP code",
+  code: "INVALID_OTP"
+}
 ```
 
 ## 🔧 Development
@@ -216,160 +226,49 @@ npm run build
 
 # Type checking
 npm run type-check
-
-# Clean build artifacts
-npm run clean
-```
-
-### Project Structure
-
-```
-payment-widget/
-├── src/
-│   ├── components/
-│   │   ├── PaymentWidget.tsx        # Main widget component
-│   │   ├── PaymentMethodSelector.tsx # Payment method selection
-│   │   ├── PaymentForm.tsx          # Payment form
-│   │   └── TransactionStatus.tsx    # Transaction status display
-│   ├── services/
-│   │   └── paymentService.ts        # API service layer
-│   ├── types/
-│   │   └── payment.ts               # TypeScript definitions
-│   ├── utils/
-│   │   ├── validation.ts            # Validation schemas
-│   │   └── index.ts                 # Utility functions
-│   ├── styles.css                   # Global styles
-│   └── index.ts                     # Main entry point
-├── dist/                            # Build output
-├── test.html                        # HTML test interface
-├── package.json
-└── README.md
 ```
 
-## 💳 Payment Methods
-
-The widget supports multiple payment methods:
-
-### Credit/Debit Cards
-- Visa
-- Mastercard
-- American Express
-- Discover
-
-### Mobile Money
-- M-Pesa (Kenya)
-- MTN Mobile Money (Ghana)
-- Airtel Money (Multiple countries)
-- Vodafone Cash (Ghana)
-
-### Bank Transfers
-- Direct bank transfers
-- ACH payments (US)
-- SEPA transfers (EU)
-
-## 🔒 Security
-
-### PCI Compliance
-
-The widget is designed to be PCI-compliant:
-
-- **No card data storage** - Card details are never stored locally
-- **Secure transmission** - All data is encrypted in transit
-- **Tokenization** - Sensitive data is tokenized for processing
-
-### API Security
-
-- All API calls include your API key
-- Request signing for additional security
-- Rate limiting protection
-
-## 📱 Mobile Support
-
-The widget is fully responsive and optimized for mobile devices:
-
-- **Touch-friendly** payment method selection
-- **Mobile-optimized** forms
-- **Responsive** design that adapts to screen size
-- **Native mobile** payment method integration
-
-## 🔄 Transaction Flow
-
-The widget handles the complete payment flow:
-
-1. **Payment Method Selection** - User chooses payment method
-2. **Form Display** - Relevant payment form is shown
-3. **Validation** - Real-time form validation
-4. **Processing** - Payment is processed securely
-5. **Status Updates** - Real-time transaction status
-6. **Completion** - Success or error handling
-
 ## 🐛 Troubleshooting
 
-### Common Issues
+### Widget doesn't open
 
-**Widget doesn't load:**
-- Check if React and ReactDOM are loaded
-- Verify the widget script is included
+- Ensure `isOpen` prop is set to `true`
 - Check browser console for errors
+- Verify React and ReactDOM are loaded
 
-**Payment methods not showing:**
-- Verify your API key has payment permissions
-- Check if payment methods are enabled for your account
-- Ensure you're in a supported region
+### Payment processing fails
 
-**Payment processing fails:**
-- Check API configuration
-- Verify payment method details
+- Verify your API key and platform ID are correct
+- Check that you have payment access enabled
+- Ensure your account has completed KYC verification
 - Check network connectivity
 - Review error messages in console
 
-**Styling issues:**
-- Ensure CSS file is loaded
-- Check for CSS conflicts with your app
-- Verify Tailwind CSS is available
+### OTP not received
 
-### Debug Mode
-
-Enable debug logging:
-
-```jsx
-<PaymentWidget
-  config={config}
-  amount={1000}
-  currency="USD"
-  onSuccess={handleSuccess}
-  onError={handleError}
-  debug={true} // Enable debug logging
-/>
-```
+- Verify phone number is correct and in E.164 format
+- Check that the selected network matches the phone number
+- Ensure you have sufficient balance for the transaction
+- Check spam folder for OTP messages
 
 ## 📄 API Reference
 
-### PaymentWidget Props
+### PaymentData
 
 ```typescript
-interface PaymentWidgetProps {
-  config: PaymentWidgetConfig;
-  amount: number; // Amount in cents
-  currency: string; // ISO currency code
-  onSuccess?: (transaction: PaymentTransaction) => void;
-  onError?: (error: PaymentError) => void;
-  onStatusChange?: (status: PaymentStatus) => void;
-  debug?: boolean;
-}
-```
-
-### PaymentTransaction
-
-```typescript
-interface PaymentTransaction {
-  id: string;
-  amount: number;
+interface PaymentData {
+  payment_id: string;
+  status: "pending" | "processing" | "completed" | "failed" | "cancelled" | "expired";
+  amount: number | string;
   currency: string;
-  status: PaymentStatus;
-  paymentMethod: string;
-  createdAt: string;
-  updatedAt: string;
+  payment_method: "mobile_money";
+  phone_number?: string;
+  network?: "mtn" | "vodafone" | "airteltigo";
+  reference?: string;
+  created_at: string;
+  updated_at: string;
+  paid_at?: string;
+  metadata?: Record<string, any>;
 }
 ```
 
@@ -383,78 +282,12 @@ interface PaymentError {
 }
 ```
 
-### PaymentStatus
-
-```typescript
-type PaymentStatus = 
-  | 'pending'      // Payment is being processed
-  | 'processing'   // Payment is being authorized
-  | 'completed'    // Payment was successful
-  | 'failed'       // Payment failed
-  | 'cancelled'    // Payment was cancelled
-  | 'refunded';    // Payment was refunded
-```
-
-## 🌍 Supported Countries
-
-The widget supports payments from multiple countries:
-
-### Africa
-- Ghana
-- Kenya
-- Nigeria
-- South Africa
-- Uganda
-- Tanzania
-
-### Europe
-- United Kingdom
-- Germany
-- France
-- Netherlands
-- Spain
-- Italy
-
-### Americas
-- United States
-- Canada
-- Brazil
-- Mexico
-
-### Asia
-- India
-- Singapore
-- Malaysia
-- Philippines
-
-## 💰 Pricing
-
-The widget is free to use. Transaction fees apply based on your Payloqa account:
-
-- **Credit/Debit Cards**: 2.9% + $0.30
-- **Mobile Money**: 1.5% + $0.10
-- **Bank Transfers**: 0.5% + $0.10
-
-*Fees may vary by region and payment method*
-
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
-
-## 📄 License
-
-MIT License - see [LICENSE](../../LICENSE) for details.
-
 ## 🆘 Support
 
 - 📧 Email: support@payloqa.com
-- 📖 Documentation: [docs.payloqa.com](https://docs.payloqa.com)
+- 📖 Documentation: [docs.payloqa.com](https://payloqa.com/developer-docs)
 - 🐛 Issues: [GitHub Issues](https://github.com/kobbycoder/payloqa-widgets/issues)
 
 ---
 
-Built with ❤️ by the Payloqa Team 
+Built with ❤️ by the Payloqa Team

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloqa/payment-widget",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "React-based payment widget for Payloqa",
   "main": "dist/index.umd.js",