npm package: @netappsng/payment-widget
Description: A simple, secure payment widget for accepting payments on your website.
Latest version: 2.0.0

# NetAppsPay Widget V2

A simple, secure payment widget for accepting payments on your website.

## Installation

### Script Tag (Recommended for most websites)

```html
<script src="https://cdn.netapps.com/netapps-pay.js"></script>
```

### NPM Package (for React projects)

```bash
npm install @netapps/payment-widget
# or
yarn add @netapps/payment-widget
```

---

## Quick Start

### Script Widget

Works with any website - HTML, WordPress, PHP, etc.

```html
<!DOCTYPE html>
<html>
<head>
  <title>Payment Page</title>
</head>
<body>
  <button id="payBtn">Pay ₦5,000</button>

  <script src="https://cdn.netapps.com/netapps-pay.js"></script>
  
  <script>
    // Initialize with your public key
    const netappsPay = new NetAppsPay('pk_live_xxxxxxxxxxxx');
    
    document.getElementById('payBtn').onclick = function() {
      netappsPay.pay({
        // Required fields
        amount: 500000,                    // Amount in kobo (₦5,000)
        email: 'customer@email.com',
        fullname: 'John Doe',
        phoneNumber: '08012345678',
        address1: '123 Main Street, Lagos',
        paymentChannels: 'card,transfer,ussd,payattitude',
        
        // Optional fields
        currency: 'NGN',
        narration: 'Payment for Order #123',
        metadata: { orderId: 'ORD_123' },
        
        // Callbacks
        onSuccessful: function(response) {
          console.log('Payment successful:', response);
          // Verify payment on your server
        },
        onFailed: function(response) {
          console.log('Payment failed:', response);
        },
        onClose: function() {
          console.log('Widget closed');
        }
      });
    };
  </script>
</body>
</html>
```

### React Integration

```tsx
import React, { useState } from 'react';
import { PaymentModal, type PaymentConfig } from '@netapps/payment-widget';

function CheckoutPage() {
  const [showPayment, setShowPayment] = useState(false);

  const config: PaymentConfig = {
    // Required fields
    publicKey: 'pk_live_xxxxxxxxxxxx',
    amount: 500000,                      // Amount in kobo (₦5,000)
    currency: 'NGN',
    email: 'customer@email.com',
    fullname: 'John Doe',
    phoneNumber: '08012345678',
    address1: '123 Main Street, Lagos',
    paymentChannels: ['card', 'transfer', 'ussd', 'payattitude'],
    
    // Optional fields
    narration: 'Payment for Order #123',
    businessName: 'My Store',
    metadata: { orderId: 'ORD_123' },
    
    // Callbacks
    onSuccess: (response) => {
      console.log('Payment successful:', response);
      setShowPayment(false);
    },
    onFailed: (response) => {
      console.log('Payment failed:', response);
    },
    onClose: () => {
      setShowPayment(false);
    },
  };

  return (
    <div>
      <button onClick={() => setShowPayment(true)}>Pay ₦5,000</button>
      {showPayment && <PaymentModal config={config} />}
    </div>
  );
}
```

---

## Configuration Options

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `amount` | number | Amount in minor units (kobo for NGN). Min: 10000 (₦100) |
| `email` | string | Customer's email address |
| `fullname` | string | Customer's full name (first and last) |
| `phoneNumber` | string | Customer's phone number |
| `address1` | string | Customer's address |
| `paymentChannels` | string/array | Payment methods to display |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `currency` | string | `'NGN'` | Currency code (`'NGN'` or `'USD'`) |
| `narration` | string | - | Payment description |
| `transactionRef` | string | Auto-generated | Your unique transaction reference |
| `chargeAllocation` | string | `'CUSTOMER'` | Who pays fees: `'CUSTOMER'` or `'MERCHANT'` |
| `metadata` | object | - | Custom data to attach to transaction |
| `businessName` | string | - | Your business name (shown in widget) |
| `city` | string | - | Customer's city |
| `defaultChannel` | string | - | Pre-selected payment channel |

### Callbacks

| Callback | Description |
|----------|-------------|
| `onSuccessful` / `onSuccess` | Called when payment is successful |
| `onFailed` | Called when payment fails |
| `onClose` | Called when widget is closed |
| `onReady` | Called when widget is ready (script only) |

---

## Payment Channels

| Channel | Code | Description |
|---------|------|-------------|
| Card | `card` | Debit/Credit card (Visa, Mastercard, Verve) |
| Bank Transfer | `transfer` | Pay via bank transfer to virtual account |
| USSD | `ussd` | Dial USSD code to complete payment |
| PayAttitude | `payattitude` | Mobile push notification payment |

**Script widget:** `paymentChannels: 'card,transfer,ussd,payattitude'`

**React:** `paymentChannels: ['card', 'transfer', 'ussd', 'payattitude']`

---

## Response Format

### Success Response

```javascript
{
  status: 'success',
  merchantRef: 'YOUR_REF_123',
  transactionRef: 'NETAPPS_260117_xxxxx',
  amount: 5000,           // Amount in major units (₦5,000)
  currency: 'NGN',
  channel: 'card',
  message: 'Payment successful',
  timestamp: '2026-01-17T12:00:00Z'
}
```

### Failed Response

```javascript
{
  status: 'failed',
  amount: 5000,
  currency: 'NGN',
  message: 'Card declined',
  errorCode: 'CARD_DECLINED',
  timestamp: '2026-01-17T12:00:00Z'
}
```

---

## Test Cards

Use these cards in test mode:

| Card Number | Expiry | CVV | Result |
|-------------|--------|-----|--------|
| 4000000000000002 | Any future date | Any 3 digits | Success |
| 5200000000000007 | Any future date | Any 3 digits | Success (3DS) |
| 4000000000000010 | Any future date | Any 3 digits | Declined |

---

## Support

- **Documentation:** https://docs.netapps.ng
- **Email:** support@netapps.ng
- **Website:** https://netapps.ng