npm package: @netappsng/pay
Description: NetApps Payment SDK - Accept card, bank transfer, USSD, and PayAttitude payments on your website
Author: NetApps Technologies
Latest version: 2.1.4

# NetAppsPay SDK V2

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

---

## Table of Contents

| Section | Description |
|---------|-------------|
| [Installation](#installation) | NPM package and Script tag installation |
| [React Integration](#react-integration) | React/Next.js implementation guide |
| [Script Widget](#script-widget) | Vanilla JS implementation for any website |
| [Configuration Options](#configuration-options) | All available parameters |
| [Payment Channels](#payment-channels) | Available payment methods |
| [Response Format](#response-format) | Success and failure response structure |
| [Test Cards](#test-cards) | Cards for testing in sandbox mode |
| [Support](#support) | Help and documentation links |

---

## Installation

### NPM Package (for React/Next.js)

```bash
npm install @netappsng/pay
# or
yarn add @netappsng/pay
```

### Script Tag (for any website)

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

---

## React Integration

### Basic Usage

```tsx
import React, { useState } from 'react';
import { PaymentModal, type PaymentConfig } from '@netappsng/pay';

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>
  );
}

export default CheckoutPage;
```

### Using the Hook

```tsx
import { useNetAppsPay } from '@netappsng/pay';

function PaymentButton() {
  const { pay, isLoading } = useNetAppsPay({
    publicKey: 'pk_live_xxxxxxxxxxxx'
    });

  const handlePayment = () => {
    pay({
      amount: 500000,
      email: 'customer@email.com',
      fullname: 'John Doe',
      phoneNumber: '08012345678',
      address1: '123 Main Street, Lagos',
      paymentChannels: ['card', 'transfer'],
      onSuccess: (response) => {
        console.log('Success:', response);
      },
      onFailed: (response) => {
        console.log('Failed:', response);
      },
      onClose: () => {
        console.log('Widget closed');
      },
    });
  };

  return (
    <button onClick={handlePayment} disabled={isLoading}>
      {isLoading ? 'Processing...' : 'Pay ₦5,000'}
    </button>
  );
}
```

### Next.js Integration

```tsx
// pages/checkout.tsx or app/checkout/page.tsx
'use client'; // Required for App Router

import dynamic from 'next/dynamic';
import { useState } from 'react';

// Dynamic import to avoid SSR issues
const PaymentModal = dynamic(
  () => import('@netappsng/pay').then(mod => mod.PaymentModal),
  { ssr: false }
);

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

  return (
    <div>
      <button onClick={() => setShowPayment(true)}>Pay Now</button>
      
      {showPayment && (
        <PaymentModal
          config={{
            publicKey: 'pk_live_xxxxxxxxxxxx',
            amount: 500000,
            email: 'customer@email.com',
            fullname: 'John Doe',
            phoneNumber: '08012345678',
            address1: '123 Main Street, Lagos',
            paymentChannels: ['card', 'transfer'],
            onSuccess: (res) => {
              console.log('Success:', res);
              setShowPayment(false);
            },
            onClose: () => setShowPayment(false),
          }}
        />
      )}
    </div>
  );
}
```

---

## Script Widget

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

### Basic Usage

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

  <script src="https://cdn.netappspay.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>
```

### Custom Widget URL

```javascript
// For testing with a different widget URL
const netappsPay = new NetAppsPay('pk_test_xxxxxxxxxxxx');
```


---

## Configuration Options

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `publicKey` | string | Your NetApps public key (starts with `pk_live_` or `pk_test_`) |
| `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) |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `currency` | string | `'NGN'` | Currency code (`'NGN'` or `'USD'`) |
| `transactionRef` | string | Auto-generated | Your unique transaction reference |
| `narration` | string | — | Payment description |
| `phoneNumber` | string | — | Customer's phone number |
| `productName` | string | — | Product name |
| `cardHolderName` | string | — | Pre-fill cardholder name on card form |
| `customerId` | string | — | Your internal customer ID |
| `address1` | string | — | Customer's address line 1 |
| `address2` | string | — | Customer's address line 2 |
| `city` | string | — | Customer's city |
| `postalCode` | string | — | Customer's postal code |
| `locality` | string | — | Country code (e.g. `'NG'`) |
| `administrativeArea` | string | — | State/province (e.g. `'Lagos'`) |
| `paymentChannels` | string/array | All channels | Payment methods to display |
| `defaultChannel` | string | — | Pre-selected payment channel |
| `chargeAllocation` | string | `'CUSTOMER'` | Who pays fees: `'CUSTOMER'` or `'MERCHANT'` |
| `metadata` | object | — | Custom data to attach to transaction |
| `businessName` | string | — | Your business name (shown in SDK) |
| `logo` | string | — | Business logo URL |
| `theme` | object/string | — | Theme configuration or preset name |
| `enableSaveCard` | boolean | `false` | Allow saving cards for returning customers |
| `enableRememberMe` | boolean | `false` | Remember customer details |
| `showTransactionSummary` | boolean | `true` | Show order summary before payment |

### Callbacks

| Callback | Description |
|----------|-------------|
| `onSuccessful` / `onSuccess` | Called when payment is successful |
| `onFailed` | Called when payment fails |
| `onClose` | Called when sdk is closed |
| `onReady` | Called when sdk 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/NPM:** `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