npm package: @moipayway/sdk
Description: MoiPayWay Payment SDK - Accept payments via card, bank transfer, USSD, mobile money, crypto and more
Author: MoiPayWay
Latest version: 3.0.0

# MoiPayWay Checkout SDK

Official MoiPayWay Payment SDK. Accept payments via **Card**, **Bank Transfer**, **USSD**, **Mobile Money**, **Pay by Bank**, **Crypto**, and more.

## Installation

### NPM / Yarn

```bash
npm install @moipayway/sdk
# or
yarn add @moipayway/sdk
```

### CDN (Vanilla JS)

```html
<script src="https://checkout.moipayway.com/sdk/v1/checkout.js"></script>
```

Or host `checkout.js` on your own server.

---

## Quick Start

### React / TypeScript

```tsx
import { MoiPayWay } from '@moipayway/sdk';

const mpw = new MoiPayWay({
  apiKey: 'your_api_key',
  environment: 'test', // 'test' or 'live'
  onSuccess: (data) => console.log('Payment successful', data),
  onError: (error) => console.error('Payment failed', error),
  onClose: () => console.log('Checkout closed'),
});

// Initiate a payment
const response = await mpw.initiate({
  amount: '5000',
  narration: 'Order #1234',
  wallet_id: 'your_wallet_id',
  user_id: 'customer@email.com',
  allow_payment_method: ['card', 'dynamic_virtual_account', 'ussd'],
});

console.log('Order ref:', response.data.order_reference_code);
```

### React Component Example

```tsx
import { useState } from 'react';
import { MoiPayWay } from '@moipayway/sdk';

function PayButton() {
  const [loading, setLoading] = useState(false);

  const handlePay = async () => {
    setLoading(true);

    const mpw = new MoiPayWay({
      apiKey: 'your_api_key',
      environment: 'test',
      onSuccess: (data) => {
        alert('Payment successful!');
        setLoading(false);
      },
      onError: (err) => {
        alert('Payment failed: ' + err.message);
        setLoading(false);
      },
    });

    try {
      const result = await mpw.initiate({
        amount: '10000',
        narration: 'Premium Plan',
        wallet_id: 'your_wallet_id',
        user_id: 'user@example.com',
        allow_payment_method: ['card', 'ussd', 'dynamic_virtual_account'],
      });

      // Use result.data.order_reference_code for further steps
      // e.g., mpw.payWithCard(orderRef, cardDetails)
    } catch (error) {
      console.error(error);
      setLoading(false);
    }
  };

  return (
    <button onClick={handlePay} disabled={loading}>
      {loading ? 'Processing...' : 'Pay ₦10,000'}
    </button>
  );
}
```

### Vanilla JavaScript

```html
<!DOCTYPE html>
<html>
<head>
  <title>MoiPayWay Checkout</title>
</head>
<body>
  <button id="pay-btn">Pay ₦5,000</button>

  <script src="https://checkout.moipayway.com/sdk/v1/checkout.js"></script>
  <script>
    const mpw = new MoiPayWay({
      apiKey: 'your_api_key',
      environment: 'test',
      onSuccess: function (data) {
        alert('Payment successful!');
        console.log(data);
      },
      onError: function (error) {
        alert('Payment failed: ' + error.message);
      },
      onClose: function () {
        console.log('Checkout closed');
      },
    });

    document.getElementById('pay-btn').addEventListener('click', async function () {
      try {
        const result = await mpw.initiate({
          amount: '5000',
          narration: 'Order #1234',
          wallet_id: 'your_wallet_id',
          user_id: 'customer@email.com',
          allow_payment_method: ['card', 'dynamic_virtual_account', 'ussd'],
        });

        console.log('Order ref:', result.data.order_reference_code);
        // Continue with payment method selection...
      } catch (err) {
        console.error('Initiation failed:', err);
      }
    });
  </script>
</body>
</html>
```

### Node.js (Server-side)

```js
const { MoiPayWay } = require('@moipayway/sdk');

const mpw = new MoiPayWay({
  apiKey: 'your_api_key',
  environment: 'live',
});

async function createPayment() {
  const result = await mpw.initiate({
    amount: '25000',
    narration: 'Invoice #5678',
    wallet_id: 'your_wallet_id',
    user_id: 'client@company.com',
    allow_payment_method: ['card', 'dynamic_virtual_account'],
  });

  return result.data.order_reference_code;
}
```

---

## API Reference

### `new MoiPayWay(config)`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `apiKey` | `string` | ✅ | Your MoiPayWay API key |
| `environment` | `'test' \| 'live'` | ✅ | API environment |
| `displayMode` | `'popup' \| 'page' \| 'iframe'` | ❌ | Checkout display mode (default: `'popup'`) |
| `onSuccess` | `(data) => void` | ❌ | Success callback |
| `onError` | `(error) => void` | ❌ | Error callback |
| `onClose` | `() => void` | ❌ | Close/cancel callback |
| `closeRedirectUrl` | `string` | ❌ | URL to redirect on close |
| `theme` | `WhiteLabelTheme` | ❌ | Custom theme colors |
| `content` | `WhiteLabelContent` | ❌ | Custom labels/text |

### Payment Methods

| Method | Description |
|--------|-------------|
| `card` | Debit/credit card (Visa, Mastercard, Verve, Afrigo) |
| `dynamic_virtual_account` | One-time bank transfer |
| `static_virtual_account` | Persistent virtual account |
| `ussd` | USSD banking |
| `pay_by_bank` | Direct bank redirect |
| `mobile_money` | Mobile money (MTN, Airtel, etc.) |
| `pay_with_crypto` | Cryptocurrency payment |

### Key Methods

```ts
// Initiate payment
mpw.initiate(meta: PaymentMeta, orderRef?: string): Promise<ApiResponse>

// Pay with card
mpw.payWithCard(orderRef: string, cardDetails: CardDetails): Promise<ApiResponse<CardResponse>>

// Authorize OTP
mpw.authorizeOTP(orderRef: string, otp: string, paymentId: string, encryptedCard: string): Promise<ApiResponse>

// Get payment info
mpw.getPaymentInfo(orderRef: string): Promise<ApiResponse<PaymentInfoResponse>>

// Get supported institutions (for USSD/bank)
mpw.getSupportedInstitutions(orderRef: string, type: string): Promise<ApiResponse>

// Simulate payment (test environment only)
mpw.simulatePayment(orderRef: string, status: string): Promise<ApiResponse>
```

---

## White-Label Theming

```ts
const mpw = new MoiPayWay({
  apiKey: 'your_key',
  environment: 'live',
  theme: {
    primaryColor: '222 60% 18%',
    accentColor: '160 84% 39%',
    borderRadius: '0.75rem',
    fontFamily: 'Inter, sans-serif',
  },
  content: {
    businessName: 'Your Brand',
    logo: 'https://yourbrand.com/logo.png',
    payButtonText: 'Complete Payment',
    hideBranding: true,
  },
});
```

---

## License

MIT