@patalink/node-api-client 1.0.5 → 1.1.0

package/README.md

@@ -1,623 +1,247 @@
-Here's a professional, detailed documentation for your `@patlink/node-api-client` package:
+# @patalink/node-api-client
 
-```markdown
-# @patlink/node-api-client - Official PataLink API Client
+[![npm version](https://img.shields.io/npm/v/@patalink/node-api-client.svg?style=flat-square)](https://www.npmjs.com/package/@patalink/node-api-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-blue.svg?style=flat-square)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/)
 
-**Server-side API client for Node.js. Accept payments programmatically with automatic encryption.**
-
-[![npm version](https://badge.fury.io/js/@patlink%2Fapi-client.svg)](https://badge.fury.io/js/@patlink%2Fapi-client)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node Version](https://img.shields.io/node/v/@patlink/node-api-client)](https://nodejs.org/)
-
----
-
-## 📖 Table of Contents
-
-- [Quick Start](#rocket-quick-start)
-- [Installation](#package-installation)
-- [Configuration](#gear-configuration)
-- [API Reference](#api-reference)
-- [Usage Examples](#usage-examples)
-- [Error Handling](#error-handling)
-- [TypeScript Support](#typescript-support)
-- [Browser Support](#browser-support)
-- [FAQ](#faq)
+The official server-side Node.js SDK for **[PataLink](https://patalink.me)**. Integrate Mobile Money collections, instant B2C payouts (MTN Rwanda), real-time wallet balances, and webhook processing with automatic end-to-end payload encryption (AES-256-CBC + HMAC-SHA256).
 
 ---
 
-## 🚀 Quick Start
-
-Add payment processing to your Node.js backend in 3 simple steps:
-
-### Step 1: Install the package
-
-```bash
-npm install @patlink/node-api-client
-```
-
-### Step 2: Initialize the client
-
-```javascript
-import { createClient } from '@patlink/node-api-client';
-
-const client = createClient({
-    apiKey: 'pk_live_abc123...',
-    encryptionKey: 'xK8j3Hd9Fq2Wm5R...',
-    baseUrl: 'https://patalink.me'
-});
-```
-
-### Step 3: Create a payment
+## ⚡ Features
 
-```javascript
-const payment = await client.createPayment({
-    amount: 25000,
-    paymentMethod: 'MTN',
-    phoneNumber: '0788888888',
-    customerName: 'John Doe',
-    customerEmail: 'john@example.com'
-});
-
-console.log('Transaction ID:', payment.transactionId);
-```
+- **Inbound Collections**: Accept customer payments via MTN Mobile Money USSD prompt and card checkout (PesaPal).
+- **Instant B2C Disbursements**: Send payouts directly to any MTN Mobile Money number in Rwanda (`078...` / `079...`).
+- **Live Wallet Balances**: Check available cleared funds, pending amounts, and total volume before initiating payouts.
+- **Automated Encryption**: Payload encryption (AES-256-CBC) and HMAC signing are handled seamlessly under the hood.
+- **Built-in Polling Utilities**: Convenient `waitForCompletion` and `waitForWithdrawalCompletion` with live progress callbacks.
+- **Universal ESM & CJS**: Full support for ES Modules (`import`), CommonJS (`require`), and TypeScript.
 
 ---
 
 ## 📦 Installation
 
-### Node.js (Recommended)
-
-```bash
-npm install @patlink/node-api-client
-```
-
-### With yarn
-
 ```bash
-yarn add @patlink/node-api-client
+npm install @patalink/node-api-client
 ```
 
-### With pnpm
-
-```bash
-pnpm add @patlink/node-api-client
-```
-
-### Requirements
-
-- Node.js 16.x or higher
-- TypeScript 4.x or higher (optional)
+*Requires Node.js 18.0.0 or higher.*
 
 ---
 
-## ⚙️ Configuration
-
-### Client Configuration Options
-
-```typescript
-interface ClientConfig {
-    apiKey: string;        // Required: Your API key from dashboard
-    encryptionKey: string; // Required: Your encryption key from dashboard  
-    baseUrl: string;       // Required: API endpoint URL
-    timeout?: number;      // Optional: Request timeout in ms (default: 30000)
-}
-```
-
-### Getting Your Keys
+## 🔑 Authentication & Prerequisites
 
-1. Sign up at [patalink.me](https://patalink.me)
-2. Navigate to **Settings** → **API Keys**
-3. Click **Generate API Key** and **Generate Encryption Key**
-4. Copy both keys to your environment variables
+To use this SDK in production:
+1. Create an account at **[patalink.me](https://patalink.me)**.
+2. Complete **KYC identity verification** in your dashboard (required for API keys and automated payouts).
+3. Navigate to **Dashboard → Settings → Security & API Keys** to copy:
+   - **API Key**: Starts with `pt_live_...` (or `pt_test_...` for sandbox)
+   - **Encryption Key**: 32-byte Base64-encoded string
 
-### Environment Setup (.env)
+Store these securely in your environment variables:
 
 ```env
-PATALINK_API_KEY=pk_live_abc123def456...
-PATALINK_ENCRYPTION_KEY=xK8j3Hd9Fq2Wm5R...
-PATALINK_BASE_URL=https://patalink.me
-```
-
-```javascript
-import { createClient } from '@patlink/node-api-client';
-
-const client = createClient({
-    apiKey: process.env.PATALINK_API_KEY,
-    encryptionKey: process.env.PATALINK_ENCRYPTION_KEY,
-    baseUrl: process.env.PATALINK_BASE_URL,
-    timeout: 30000  // optional
-});
+PATALINK_API_KEY=pt_live_your_api_key_here
+PATALINK_ENCRYPTION_KEY=your_base64_encryption_key_here
+PATALINK_BASE_URL=https://api.patalink.me
 ```
 
 ---
 
-## 📚 API Reference
-
-### `createPayment(request)`
-
-Create a new payment transaction.
+## 🚀 Quick Start
 
-**Parameters:**
+Initialize the client once in your application:
 
 ```typescript
-interface PaymentRequest {
-    amount: number;                    // Required: Amount in RWF (min 100, max 2,000,000 for mobile money)
-    currency?: string;                 // Optional: Currency code (default: 'RWF')
-    paymentMethod: 'MTN' | 'Airtel' | 'PesaPal';  // Required: Payment method
-    phoneNumber?: string;              // Required for MTN/Airtel
-    customerName?: string;             // Optional: Customer's full name
-    customerEmail?: string;            // Optional: Customer's email address
-}
-```
-
-**Returns:**
+import { createClient } from '@patalink/node-api-client';
 
-```typescript
-interface PaymentResponse {
-    transactionId: string;             // Unique transaction identifier
-    status: 'pending' | 'success' | 'failed';  // Current payment status
-    providerRef?: string;              // Payment provider reference
-    redirectUrl?: string;              // For PesaPal card payments
-    message?: string;                  // Additional response message
-}
+const client = createClient({
+  apiKey: process.env.PATALINK_API_KEY!,
+  encryptionKey: process.env.PATALINK_ENCRYPTION_KEY!,
+  baseUrl: process.env.PATALINK_BASE_URL || 'https://api.patalink.me'
+});
 ```
 
-**Example:**
-
+*CommonJS syntax is also fully supported:*
 ```javascript
-// MTN Mobile Money
-const payment = await client.createPayment({
-    amount: 25000,
-    paymentMethod: 'MTN',
-    phoneNumber: '0788888888',
-    customerName: 'John Doe',
-    customerEmail: 'john@example.com'
-});
-
-// Card Payment (PesaPal)
-const cardPayment = await client.createPayment({
-    amount: 50000,
-    paymentMethod: 'PesaPal',
-    customerName: 'Jane Smith',
-    customerEmail: 'jane@example.com'
-});
-
-// Handle redirect for card payments
-if (cardPayment.redirectUrl) {
-    // Redirect user to payment page
-    res.redirect(cardPayment.redirectUrl);
-}
+const { createClient } = require('@patalink/node-api-client');
 ```
 
 ---
 
-### `getTransactionStatus(transactionId)`
-
-Get the current status of a transaction.
+## 📖 Usage Examples
 
-**Parameters:**
+### 1. Inbound Collections (Customer Payments)
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `transactionId` | `string` | Transaction ID from `createPayment` response |
-
-**Returns:**
+Trigger a payment prompt on the customer's phone (MTN MoMo) or generate a checkout redirect for card payments (PesaPal):
 
 ```typescript
-interface TransactionStatus {
-    id: string;                        // Transaction ID
-    status: 'pending' | 'success' | 'failed';  // Current status
-    amount: number;                    // Transaction amount
-    currency: string;                  // Currency code
-    paymentMethod: string;             // Payment method used
-    createdAt: string;                 // ISO timestamp of creation
-    completedAt?: string;              // ISO timestamp of completion
-    providerRef?: string;              // Provider reference
-}
-```
+// 1. Initiate payment request
+const payment = await client.createPayment({
+  amount: 5000,                            // Amount in RWF (min 100 RWF)
+  paymentMethod: 'MTN',                    // 'MTN' or 'PesaPal'
+  phoneNumber: '0788820857',               // Customer Mobile Money number
+  customerName: 'Alice Umutoni',           // Optional
+  customerEmail: 'alice@example.com',      // Optional
+  callbackUrl: 'https://example.com/done'  // Required for Card payments
+});
 
-**Example:**
+console.log('Payment Initiated! Transaction ID:', payment.transactionId);
 
-```javascript
-const status = await client.getTransactionStatus('txn_abc123');
+// 2. Poll until customer confirms payment with their MoMo PIN
+const verified = await client.waitForCompletion(payment.transactionId, {
+  maxAttempts: 30,                         // Poll up to 30 times
+  interval: 2500,                          // Check every 2.5 seconds
+  onProgress: (attempt, status) => {
+    console.log(`Poll #${attempt}: Status is ${status}`);
+  }
+});
 
-if (status.status === 'success') {
-    console.log('Payment completed at:', status.completedAt);
-} else if (status.status === 'pending') {
-    console.log('Still waiting for confirmation...');
+if (verified.status === 'success') {
+  console.log('✅ Payment confirmed! Deliver goods or grant access.');
 } else {
-    console.log('Payment failed');
+  console.log('❌ Payment failed or expired.');
 }
 ```
 
 ---
 
-## 💡 Usage Examples
+### 2. Instant B2C Disbursements (Payouts)
 
-### Webhook Endpoint (Express.js)
-
-```javascript
-import express from 'express';
-import { createClient } from '@patlink/node-api-client';
-
-const app = express();
-const client = createClient({
-    apiKey: process.env.PATALINK_API_KEY,
-    encryptionKey: process.env.PATALINK_ENCRYPTION_KEY,
-    baseUrl: process.env.PATALINK_BASE_URL
-});
-
-app.post('/api/create-payment', async (req, res) => {
-    try {
-        const { amount, phoneNumber, customerName, customerEmail } = req.body;
-        
-        const payment = await client.createPayment({
-            amount,
-            paymentMethod: 'MTN',
-            phoneNumber,
-            customerName,
-            customerEmail
-        });
-        
-        res.json({
-            success: true,
-            transactionId: payment.transactionId,
-            status: payment.status
-        });
-    } catch (error) {
-        res.status(400).json({
-            success: false,
-            error: error.message
-        });
-    }
-});
-
-app.get('/api/payment-status/:transactionId', async (req, res) => {
-    try {
-        const status = await client.getTransactionStatus(req.params.transactionId);
-        res.json(status);
-    } catch (error) {
-        res.status(404).json({ error: error.message });
-    }
-});
-
-app.listen(3000, () => {
-    console.log('Server running on port 3000');
-});
-```
-
-### Polling Implementation
-
-```javascript
-async function pollPaymentStatus(transactionId, maxAttempts = 30, interval = 2000) {
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        console.log(`Checking status (attempt ${attempt}/${maxAttempts})...`);
-        
-        const status = await client.getTransactionStatus(transactionId);
-        
-        if (status.status === 'success') {
-            console.log('✅ Payment successful!');
-            return status;
-        }
-        
-        if (status.status === 'failed') {
-            console.log('❌ Payment failed!');
-            return status;
-        }
-        
-        // Wait before next attempt
-        await new Promise(resolve => setTimeout(resolve, interval));
-    }
-    
-    throw new Error('Payment timeout - still pending after maximum attempts');
-}
-
-// Usage
-const transaction = await client.createPayment({
-    amount: 25000,
-    paymentMethod: 'MTN',
-    phoneNumber: '0788888888'
-});
-
-const result = await pollPaymentStatus(transaction.transactionId);
-console.log('Final status:', result.status);
-```
-
-### Next.js API Route
+Send funds directly from your PataLink cleared wallet balance to any MTN Mobile Money number in Rwanda:
 
 ```typescript
-// app/api/payments/route.ts
-import { NextResponse } from 'next/server';
-import { createClient } from '@patlink/node-api-client';
-
-const client = createClient({
-    apiKey: process.env.PATALINK_API_KEY!,
-    encryptionKey: process.env.PATALINK_ENCRYPTION_KEY!,
-    baseUrl: process.env.PATALINK_BASE_URL!
+// 1. Dispatch payout
+const payout = await client.createWithdrawal({
+  amount: 25000,                           // Amount in RWF (min 1,000, max 2,000,000)
+  destinationNumber: '0788820857',         // MTN Rwanda number (078... / 079...)
+  network: 'MTN',                          // Network (default: 'MTN')
+  reference: 'PAYOUT-ORD-9021',            // Optional: Your internal reference
+  recipientNote: 'Weekly Creator Earnings',// Optional: Note to recipient
+  idempotencyKey: 'payout-uuid-v4'         // Optional: Prevents duplicate transfers
 });
 
-export async function POST(request: Request) {
-    try {
-        const body = await request.json();
-        
-        const payment = await client.createPayment({
-            amount: body.amount,
-            paymentMethod: body.paymentMethod,
-            phoneNumber: body.phoneNumber,
-            customerName: body.customerName,
-            customerEmail: body.customerEmail
-        });
-        
-        return NextResponse.json(payment);
-    } catch (error: any) {
-        return NextResponse.json(
-            { error: error.message },
-            { status: 400 }
-        );
-    }
-}
-
-export async function GET(request: Request) {
-    const { searchParams } = new URL(request.url);
-    const transactionId = searchParams.get('transactionId');
-    
-    if (!transactionId) {
-        return NextResponse.json(
-            { error: 'transactionId is required' },
-            { status: 400 }
-        );
-    }
-    
-    try {
-        const status = await client.getTransactionStatus(transactionId);
-        return NextResponse.json(status);
-    } catch (error: any) {
-        return NextResponse.json(
-            { error: error.message },
-            { status: 404 }
-        );
-    }
-}
-```
+console.log('Payout Submitted:', payout.id, 'Status:', payout.status);
 
-### Bulk Payment Processing
+// 2. Poll until terminal status (paid or failed)
+const finalPayout = await client.waitForWithdrawalCompletion(payout.id, {
+  maxAttempts: 30,
+  interval: 2000,
+  onProgress: (attempt, status) => {
+    console.log(`Disbursement Poll #${attempt}: ${status}`);
+  }
+});
 
-```javascript
-async function processBulkPayments(payments) {
-    const results = [];
-    
-    for (const payment of payments) {
-        try {
-            const result = await client.createPayment(payment);
-            results.push({
-                success: true,
-                transactionId: result.transactionId,
-                amount: payment.amount,
-                phoneNumber: payment.phoneNumber
-            });
-        } catch (error) {
-            results.push({
-                success: false,
-                error: error.message,
-                amount: payment.amount,
-                phoneNumber: payment.phoneNumber
-            });
-        }
-        
-        // Rate limiting - avoid overwhelming the API
-        await new Promise(resolve => setTimeout(resolve, 500));
-    }
-    
-    return results;
+if (finalPayout.status === 'paid') {
+  console.log('✅ Funds delivered to recipient mobile wallet!');
 }
-
-// Usage
-const payments = [
-    { amount: 10000, paymentMethod: 'MTN', phoneNumber: '0788888888' },
-    { amount: 25000, paymentMethod: 'Airtel', phoneNumber: '0789999999' },
-    { amount: 5000, paymentMethod: 'MTN', phoneNumber: '0787777777' }
-];
-
-const results = await processBulkPayments(payments);
-console.log(results);
 ```
 
 ---
 
-## 🚨 Error Handling
+### 3. Check Wallet Balances & Account Info
 
-### Common Errors
+Verify your merchant cleared balance before initiating payouts:
 
-```javascript
-try {
-    const payment = await client.createPayment({
-        amount: 500,
-        paymentMethod: 'MTN',
-        phoneNumber: '0788888888'
-    });
-} catch (error) {
-    switch (error.message) {
-        case 'Amount must be at least 100 RWF':
-            // Handle minimum amount error
-            break;
-        case 'Mobile Money limit is 2,000,000 RWF':
-            // Handle maximum amount error
-            break;
-        case 'phoneNumber is required for mobile money payments':
-            // Handle missing phone number
-            break;
-        case 'Request timeout':
-            // Handle timeout - implement retry logic
-            break;
-        default:
-            // Handle other errors
-            console.error('Payment failed:', error.message);
-    }
-}
-```
+```typescript
+const account = await client.getAccountInfo();
 
-### Retry Logic with Exponential Backoff
+console.log('User ID:           ', account.id);
+console.log('Available Cleared: ', account.availableBalance, 'RWF');
+console.log('Total Gross Volume:', account.walletBalance, 'RWF');
+console.log('Pending Funds:     ', account.pendingBalance, 'RWF');
 
-```javascript
-async function createPaymentWithRetry(request, maxRetries = 3) {
-    let lastError;
-    
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-        try {
-            return await client.createPayment(request);
-        } catch (error) {
-            lastError = error;
-            
-            if (attempt === maxRetries) break;
-            
-            // Exponential backoff: 1s, 2s, 4s
-            const delay = Math.pow(2, attempt - 1) * 1000;
-            console.log(`Retry ${attempt}/${maxRetries} after ${delay}ms...`);
-            await new Promise(resolve => setTimeout(resolve, delay));
-        }
-    }
-    
-    throw lastError;
+// Example: Guard payout against insufficient balance
+if (account.availableBalance < 50000) {
+  throw new Error('Insufficient cleared balance to perform payout');
 }
-
-// Usage
-const payment = await createPaymentWithRetry({
-    amount: 25000,
-    paymentMethod: 'MTN',
-    phoneNumber: '0788888888'
-});
 ```
 
 ---
 
-## 🔷 TypeScript Support
+### 4. Webhook Listener (Express / Node.js)
 
-Full TypeScript support with complete type definitions.
+Configure a webhook endpoint in your server to receive asynchronous real-time events for collections and disbursements:
 
-### Type Definitions
-
-```typescript
-import { createClient, PaymentRequest, PaymentResponse, TransactionStatus } from '@patlink/node-api-client';
+```javascript
+import express from 'express';
 
-const client = createClient({
-    apiKey: process.env.PATALINK_API_KEY!,
-    encryptionKey: process.env.PATALINK_ENCRYPTION_KEY!,
-    baseUrl: process.env.PATALINK_BASE_URL!
+const app = express();
+app.use(express.json());
+
+app.post('/api/webhooks/patalink', (req, res) => {
+  const { event, data } = req.body;
+
+  // Handle Payout Events (Disbursements)
+  if (event === 'withdrawal.paid') {
+    console.log(`✅ Payout Delivered: ${data.withdrawalId} (${data.amount} RWF)`);
+    // Update order status in your database
+  } else if (event === 'withdrawal.failed') {
+    console.log(`❌ Payout Failed: ${data.withdrawalId} - Reason: ${data.failureReason}`);
+  }
+
+  // Handle Collection Events (Inbound Payments)
+  else if (event === 'payment.completed' || req.body.status === 'success') {
+    const txnId = req.body.transactionId || data?.transactionId;
+    console.log(`💰 Inbound Payment Confirmed: ${txnId}`);
+    // Fulfill customer order
+  }
+
+  // Always respond with 200 OK immediately
+  res.status(200).send('OK');
 });
 
-async function processPayment(request: PaymentRequest): Promise<PaymentResponse> {
-    const payment = await client.createPayment(request);
-    return payment;
-}
-
-async function checkStatus(transactionId: string): Promise<TransactionStatus> {
-    const status = await client.getTransactionStatus(transactionId);
-    return status;
-}
+app.listen(3000, () => console.log('Webhook server running on port 3000'));
 ```
 
 ---
 
-## 🌐 Browser Support
+## 🧪 Sandbox & Testing
 
-This package is designed for **Node.js server-side** use only. For browser/client-side integration, use our HTML web component:
+You can test full workflows in the sandbox without touching real money:
+- Use an API key starting with `pt_test_...`.
+- Use test phone number `0788820857`.
+- **Withdrawal Simulation Conventions**:
+  - Amounts ending in `99` (e.g., `1099 RWF`) simulate a **failed disbursement**.
+  - Amounts ending in `55` (e.g., `1555 RWF`) stay **pending** for testing timeout handling.
+  - All other amounts automatically transition to **paid**.
 
-```html
-<script type="module">
-    import 'https://esm.sh/@patlink/html-payment-modal';
-</script>
-
-<payment-modal
-    base-url="https://patalink.me"
-    api-key="your_api_key"
-    encryption-key="your_encryption_key"
-></payment-modal>
-```
+Try out live requests in the interactive **[PataLink Developer Playground](https://patalink.me/developer/docs)** before writing code.
 
 ---
 
-## ❓ FAQ
-
-### Can I use this in the browser?
-
-**No.** This package uses server-side encryption and should only be used in Node.js environments. For browser payments, use our HTML web component instead.
-
-### How do I get my API and encryption keys?
-
-1. Sign up at [dashboard.patalink.me](https://dashboard.patalink.me)
-2. Go to **Settings** → **API Keys**
-3. Click **Generate API Key** and **Generate Encryption Key**
-4. Store both keys securely in environment variables
-
-### What's the difference between API key and encryption key?
-
-- **API Key**: Identifies your account (authentication)
-- **Encryption Key**: Encrypts payment data (security)
-
-Both are required and should be kept secret.
-
-### What payment methods are supported?
-
-- MTN Mobile Money
-- Airtel Money  
-- Credit/Debit Cards (via PesaPal)
-
-### What's the minimum and maximum payment amount?
-
-- **Minimum**: 100 RWF
-- **Maximum for Mobile Money**: 2,000,000 RWF
-- **Maximum for Cards**: No limit (subject to card issuer)
-
-### How do I handle card payment redirects?
-
-For PesaPal card payments, the response includes a `redirectUrl`. You need to redirect your user to this URL to complete the payment.
-
-```javascript
-const payment = await client.createPayment({
-    amount: 50000,
-    paymentMethod: 'PesaPal',
-    customerEmail: 'customer@example.com'
-});
-
-if (payment.redirectUrl) {
-    res.redirect(payment.redirectUrl);
-}
-```
-
-### Is the encryption automatic?
-
-**Yes.** The client automatically encrypts all payment data before sending to our API. You don't need to implement any encryption logic.
-
-### Can I test without real money?
-
-**Yes.** Use your test keys from the dashboard (they start with `pk_test_`). Test transactions are processed in sandbox mode.
+## 📚 API Reference
 
-### What happens if a request times out?
+### `createClient(config: ClientConfig): PataLinkClient`
 
-The client will throw a timeout error after the configured timeout period (default 30 seconds). You should implement retry logic with exponential backoff.
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | Yes | Your PataLink API key (`pt_live_...` or `pt_test_...`) |
+| `encryptionKey` | `string` | Yes | 32-byte Base64 encryption key from dashboard |
+| `baseUrl` | `string` | No | API endpoint (defaults to `https://api.patalink.me`) |
+| `timeout` | `number` | No | Request timeout in milliseconds (default: 30000) |
 
-### How do I know if a payment is complete?
+### Client Methods
 
-1. Check the `status` field in the `createPayment` response
-2. For pending payments, use `getTransactionStatus` to poll
-3. Or set up webhooks to receive real-time updates
+- `client.createPayment(request: PaymentRequest): Promise<PaymentResponse>`
+- `client.getTransactionStatus(transactionId: string): Promise<TransactionStatus>`
+- `client.waitForCompletion(transactionId: string, options?): Promise<TransactionStatus>`
+- `client.createWithdrawal(request: WithdrawalRequest): Promise<WithdrawalResponse>`
+- `client.getWithdrawalStatus(withdrawalId: string): Promise<WithdrawalStatus>`
+- `client.waitForWithdrawalCompletion(withdrawalId: string, options?): Promise<WithdrawalStatus>`
+- `client.getAccountInfo(): Promise<AccountInfo>`
+- `client.listTransactions(options?): Promise<{ transactions, total }>`
+- `client.listWithdrawals(options?): Promise<{ withdrawals, total }>`
 
 ---
 
-## 📞 Support
+## 🔒 Security
 
-- 📖 [Full API Documentation](https://docs.patalink.me)
-- 💬 [Discord Community](https://discord.gg/patlink)
-- 🐛 [GitHub Issues](https://github.com/patlink/api-client/issues)
-- ✉️ [support@patalink.me](mailto:support@patalink.me)
+All transaction initiation requests to PataLink are protected by **AES-256-CBC payload encryption** and signed with an **HMAC-SHA256 signature** generated using your secret encryption key. This SDK handles encryption and signing automatically for every request.
 
 ---
 
 ## 📄 License
 
 MIT © [PataLink](https://patalink.me)
-
----
-
-**Secure, encrypted payments for your Node.js backend.** 🚀
-```

package/dist/index.d.mts

@@ -24,6 +24,43 @@ interface TransactionStatus {
     completedAt?: string;
     providerRef?: string;
 }
+interface WithdrawalRequest {
+    amount: number;
+    destinationNumber?: string;
+    phoneNumber?: string;
+    network?: 'MTN';
+    reference?: string;
+    recipientNote?: string;
+    callbackUrl?: string;
+    idempotencyKey?: string;
+}
+interface WithdrawalResponse {
+    id: string;
+    withdrawalId: string;
+    status: 'processing' | 'pending' | 'paid' | 'rejected' | 'failed';
+    amount: number;
+    feeAmount: number;
+    netAmount: number;
+    currency: string;
+    destinationNumber: string;
+    network: 'MTN';
+    reference?: string;
+    providerRef?: string;
+    externalId?: string;
+    createdAt: string;
+}
+interface WithdrawalStatus {
+    id: string;
+    status: 'processing' | 'pending' | 'paid' | 'rejected' | 'failed';
+    amount: number;
+    destinationNumber: string;
+    network: 'MTN';
+    reference?: string;
+    providerRef?: string;
+    reason?: string;
+    processedAt?: string;
+    createdAt: string;
+}
 interface ClientConfig {
     apiKey: string;
     encryptionKey: string;
@@ -89,17 +126,21 @@ declare class PataLinkClient {
         availableBalance: number;
     }>;
     /**
-     * Initiate withdrawal
+     * Initiate a withdrawal / payout (MTN Mobile Money)
      */
-    createWithdrawal(request: {
-        amount: number;
-        phoneNumber: string;
-        network: 'MTN' | 'Airtel';
-    }): Promise<{
-        withdrawalId: string;
-        status: string;
-        message: string;
-    }>;
+    createWithdrawal(request: WithdrawalRequest): Promise<WithdrawalResponse>;
+    /**
+     * Get withdrawal status by ID, external ID, or reference
+     */
+    getWithdrawalStatus(withdrawalId: string): Promise<WithdrawalStatus>;
+    /**
+     * Poll until withdrawal reaches a terminal status (paid, rejected, or failed)
+     */
+    waitForWithdrawalCompletion(withdrawalId: string, options?: {
+        maxAttempts?: number;
+        interval?: number;
+        onProgress?: (attempt: number, status: string) => void;
+    }): Promise<WithdrawalStatus>;
     /**
      * List withdrawals
      */
@@ -113,4 +154,4 @@ declare class PataLinkClient {
 }
 declare function createClient(config: ClientConfig): PataLinkClient;
 
-export { type ClientConfig, type PaymentRequest, type PaymentResponse, type TransactionStatus, createClient, PataLinkClient as default };
+export { type ClientConfig, type PaymentRequest, type PaymentResponse, type TransactionStatus, type WithdrawalRequest, type WithdrawalResponse, type WithdrawalStatus, createClient, PataLinkClient as default };

package/dist/index.d.ts

@@ -24,6 +24,43 @@ interface TransactionStatus {
     completedAt?: string;
     providerRef?: string;
 }
+interface WithdrawalRequest {
+    amount: number;
+    destinationNumber?: string;
+    phoneNumber?: string;
+    network?: 'MTN';
+    reference?: string;
+    recipientNote?: string;
+    callbackUrl?: string;
+    idempotencyKey?: string;
+}
+interface WithdrawalResponse {
+    id: string;
+    withdrawalId: string;
+    status: 'processing' | 'pending' | 'paid' | 'rejected' | 'failed';
+    amount: number;
+    feeAmount: number;
+    netAmount: number;
+    currency: string;
+    destinationNumber: string;
+    network: 'MTN';
+    reference?: string;
+    providerRef?: string;
+    externalId?: string;
+    createdAt: string;
+}
+interface WithdrawalStatus {
+    id: string;
+    status: 'processing' | 'pending' | 'paid' | 'rejected' | 'failed';
+    amount: number;
+    destinationNumber: string;
+    network: 'MTN';
+    reference?: string;
+    providerRef?: string;
+    reason?: string;
+    processedAt?: string;
+    createdAt: string;
+}
 interface ClientConfig {
     apiKey: string;
     encryptionKey: string;
@@ -89,17 +126,21 @@ declare class PataLinkClient {
         availableBalance: number;
     }>;
     /**
-     * Initiate withdrawal
+     * Initiate a withdrawal / payout (MTN Mobile Money)
      */
-    createWithdrawal(request: {
-        amount: number;
-        phoneNumber: string;
-        network: 'MTN' | 'Airtel';
-    }): Promise<{
-        withdrawalId: string;
-        status: string;
-        message: string;
-    }>;
+    createWithdrawal(request: WithdrawalRequest): Promise<WithdrawalResponse>;
+    /**
+     * Get withdrawal status by ID, external ID, or reference
+     */
+    getWithdrawalStatus(withdrawalId: string): Promise<WithdrawalStatus>;
+    /**
+     * Poll until withdrawal reaches a terminal status (paid, rejected, or failed)
+     */
+    waitForWithdrawalCompletion(withdrawalId: string, options?: {
+        maxAttempts?: number;
+        interval?: number;
+        onProgress?: (attempt: number, status: string) => void;
+    }): Promise<WithdrawalStatus>;
     /**
      * List withdrawals
      */
@@ -113,4 +154,4 @@ declare class PataLinkClient {
 }
 declare function createClient(config: ClientConfig): PataLinkClient;
 
-export { type ClientConfig, type PaymentRequest, type PaymentResponse, type TransactionStatus, createClient, PataLinkClient as default };
+export { type ClientConfig, type PaymentRequest, type PaymentResponse, type TransactionStatus, type WithdrawalRequest, type WithdrawalResponse, type WithdrawalStatus, createClient, PataLinkClient as default };

package/dist/index.js

@@ -34,7 +34,7 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var CryptoJS = __toESM(require("crypto-js"));
+var import_crypto_js = __toESM(require("crypto-js"));
 var PataLinkClient = class {
   constructor(config) {
     if (!config.apiKey) throw new Error("API key is required");
@@ -52,20 +52,20 @@ var PataLinkClient = class {
     const dataString = JSON.stringify(data);
     let keyWA;
     try {
-      keyWA = CryptoJS.enc.Base64.parse(this.encryptionKey);
+      keyWA = import_crypto_js.default.enc.Base64.parse(this.encryptionKey);
     } catch (error) {
-      keyWA = CryptoJS.enc.Utf8.parse(this.encryptionKey);
+      keyWA = import_crypto_js.default.enc.Utf8.parse(this.encryptionKey);
     }
-    const iv = CryptoJS.lib.WordArray.random(16);
-    const ivHex = iv.toString(CryptoJS.enc.Hex);
-    const ivWA = CryptoJS.enc.Hex.parse(ivHex);
-    const encrypted = CryptoJS.AES.encrypt(dataString, keyWA, {
+    const iv = import_crypto_js.default.lib.WordArray.random(16);
+    const ivHex = iv.toString(import_crypto_js.default.enc.Hex);
+    const ivWA = import_crypto_js.default.enc.Hex.parse(ivHex);
+    const encrypted = import_crypto_js.default.AES.encrypt(dataString, keyWA, {
       iv: ivWA,
-      mode: CryptoJS.mode.CBC,
-      padding: CryptoJS.pad.Pkcs7
+      mode: import_crypto_js.default.mode.CBC,
+      padding: import_crypto_js.default.pad.Pkcs7
     });
-    const encryptedBase64 = encrypted.ciphertext.toString(CryptoJS.enc.Base64);
-    const hmac = CryptoJS.HmacSHA256(dataString, keyWA).toString();
+    const encryptedBase64 = encrypted.ciphertext.toString(import_crypto_js.default.enc.Base64);
+    const hmac = import_crypto_js.default.HmacSHA256(dataString, keyWA).toString();
     return {
       encrypted: encryptedBase64,
       iv: ivHex,
@@ -132,7 +132,7 @@ var PataLinkClient = class {
       paymentData.callbackUrl = request.callbackUrl;
     }
     const encryptedPayload = this.encrypt(paymentData);
-    const response = await this.request("/api/pay", {
+    const response = await this.request("/pay", {
       method: "POST",
       headers: {
         "x-encrypted": "true"
@@ -146,7 +146,7 @@ var PataLinkClient = class {
    */
   async getTransactionStatus(transactionId) {
     if (!transactionId) throw new Error("transactionId is required");
-    return await this.request(`/api/pay/${transactionId}`, {
+    return await this.request(`/pay/${transactionId}`, {
       method: "GET"
     });
   }
@@ -159,8 +159,8 @@ var PataLinkClient = class {
     let attempts = 0;
     while (attempts < maxAttempts) {
       attempts++;
-      options?.onProgress?.(attempts, "checking");
       const status = await this.getTransactionStatus(transactionId);
+      options?.onProgress?.(attempts, status.status);
       if (status.status === "success" || status.status === "failed") {
         return status;
       }
@@ -177,7 +177,7 @@ var PataLinkClient = class {
     if (options?.offset) params.append("offset", options.offset.toString());
     if (options?.status) params.append("status", options.status);
     const query = params.toString();
-    const endpoint = `/api/transactions${query ? `?${query}` : ""}`;
+    const endpoint = `/transactions${query ? `?${query}` : ""}`;
     return this.request(endpoint, {
       method: "GET"
     });
@@ -186,7 +186,7 @@ var PataLinkClient = class {
    * Rotate encryption key (generates new key, revokes old one after 24h)
    */
   async rotateEncryptionKey() {
-    return this.request("/api/keys/rotate", {
+    return this.request("/keys/rotate", {
       method: "POST"
     });
   }
@@ -194,24 +194,67 @@ var PataLinkClient = class {
    * Get account information
    */
   async getAccountInfo() {
-    return this.request("/api/account", { method: "GET" });
+    return this.request("/account", { method: "GET" });
   }
   /**
-   * Initiate withdrawal
+   * Initiate a withdrawal / payout (MTN Mobile Money)
    */
   async createWithdrawal(request) {
+    const destination = request.destinationNumber || request.phoneNumber;
     if (!request.amount) throw new Error("amount is required");
-    if (!request.phoneNumber) throw new Error("phoneNumber is required");
-    if (request.amount < 100) throw new Error("Minimum withdrawal is 100 RWF");
+    if (!destination) throw new Error("destinationNumber is required");
+    if (request.amount < 1e3) throw new Error("Minimum withdrawal is 1,000 RWF");
     if (request.amount > 2e6) throw new Error("Maximum withdrawal is 2,000,000 RWF");
-    const encryptedPayload = this.encrypt(request);
-    return this.request("/api/withdrawals", {
+    const withdrawalData = {
+      amount: request.amount,
+      destinationNumber: destination,
+      network: request.network || "MTN",
+      ...request.reference && { reference: request.reference },
+      ...request.recipientNote && { recipientNote: request.recipientNote },
+      ...request.callbackUrl && { callbackUrl: request.callbackUrl },
+      ...request.idempotencyKey && { idempotencyKey: request.idempotencyKey }
+    };
+    const encryptedPayload = this.encrypt(withdrawalData);
+    const headers = {
+      "x-encrypted": "true"
+    };
+    if (request.idempotencyKey) {
+      headers["Idempotency-Key"] = request.idempotencyKey;
+    }
+    const response = await this.request("/withdraw", {
       method: "POST",
-      headers: {
-        "x-encrypted": "true"
-      },
+      headers,
       body: JSON.stringify(encryptedPayload)
     });
+    response.withdrawalId = response.id;
+    return response;
+  }
+  /**
+   * Get withdrawal status by ID, external ID, or reference
+   */
+  async getWithdrawalStatus(withdrawalId) {
+    if (!withdrawalId) throw new Error("withdrawalId is required");
+    return await this.request(`/withdraw/${withdrawalId}`, {
+      method: "GET"
+    });
+  }
+  /**
+   * Poll until withdrawal reaches a terminal status (paid, rejected, or failed)
+   */
+  async waitForWithdrawalCompletion(withdrawalId, options) {
+    const maxAttempts = options?.maxAttempts || 60;
+    const interval = options?.interval || 3e3;
+    let attempts = 0;
+    while (attempts < maxAttempts) {
+      attempts++;
+      const status = await this.getWithdrawalStatus(withdrawalId);
+      options?.onProgress?.(attempts, status.status);
+      if (status.status === "paid" || status.status === "rejected" || status.status === "failed") {
+        return status;
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    throw new Error("Withdrawal timeout - still processing after maximum attempts");
   }
   /**
    * List withdrawals
@@ -221,7 +264,7 @@ var PataLinkClient = class {
     if (options?.limit) params.append("limit", options.limit.toString());
     if (options?.offset) params.append("offset", options.offset.toString());
     const query = params.toString();
-    const endpoint = `/api/withdrawals${query ? `?${query}` : ""}`;
+    const endpoint = `/withdrawals${query ? `?${query}` : ""}`;
     return this.request(endpoint, { method: "GET" });
   }
 };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-import * as CryptoJS from "crypto-js";
+import CryptoJS from "crypto-js";
 var PataLinkClient = class {
   constructor(config) {
     if (!config.apiKey) throw new Error("API key is required");
@@ -97,7 +97,7 @@ var PataLinkClient = class {
       paymentData.callbackUrl = request.callbackUrl;
     }
     const encryptedPayload = this.encrypt(paymentData);
-    const response = await this.request("/api/pay", {
+    const response = await this.request("/pay", {
       method: "POST",
       headers: {
         "x-encrypted": "true"
@@ -111,7 +111,7 @@ var PataLinkClient = class {
    */
   async getTransactionStatus(transactionId) {
     if (!transactionId) throw new Error("transactionId is required");
-    return await this.request(`/api/pay/${transactionId}`, {
+    return await this.request(`/pay/${transactionId}`, {
       method: "GET"
     });
   }
@@ -124,8 +124,8 @@ var PataLinkClient = class {
     let attempts = 0;
     while (attempts < maxAttempts) {
       attempts++;
-      options?.onProgress?.(attempts, "checking");
       const status = await this.getTransactionStatus(transactionId);
+      options?.onProgress?.(attempts, status.status);
       if (status.status === "success" || status.status === "failed") {
         return status;
       }
@@ -142,7 +142,7 @@ var PataLinkClient = class {
     if (options?.offset) params.append("offset", options.offset.toString());
     if (options?.status) params.append("status", options.status);
     const query = params.toString();
-    const endpoint = `/api/transactions${query ? `?${query}` : ""}`;
+    const endpoint = `/transactions${query ? `?${query}` : ""}`;
     return this.request(endpoint, {
       method: "GET"
     });
@@ -151,7 +151,7 @@ var PataLinkClient = class {
    * Rotate encryption key (generates new key, revokes old one after 24h)
    */
   async rotateEncryptionKey() {
-    return this.request("/api/keys/rotate", {
+    return this.request("/keys/rotate", {
       method: "POST"
     });
   }
@@ -159,24 +159,67 @@ var PataLinkClient = class {
    * Get account information
    */
   async getAccountInfo() {
-    return this.request("/api/account", { method: "GET" });
+    return this.request("/account", { method: "GET" });
   }
   /**
-   * Initiate withdrawal
+   * Initiate a withdrawal / payout (MTN Mobile Money)
    */
   async createWithdrawal(request) {
+    const destination = request.destinationNumber || request.phoneNumber;
     if (!request.amount) throw new Error("amount is required");
-    if (!request.phoneNumber) throw new Error("phoneNumber is required");
-    if (request.amount < 100) throw new Error("Minimum withdrawal is 100 RWF");
+    if (!destination) throw new Error("destinationNumber is required");
+    if (request.amount < 1e3) throw new Error("Minimum withdrawal is 1,000 RWF");
     if (request.amount > 2e6) throw new Error("Maximum withdrawal is 2,000,000 RWF");
-    const encryptedPayload = this.encrypt(request);
-    return this.request("/api/withdrawals", {
+    const withdrawalData = {
+      amount: request.amount,
+      destinationNumber: destination,
+      network: request.network || "MTN",
+      ...request.reference && { reference: request.reference },
+      ...request.recipientNote && { recipientNote: request.recipientNote },
+      ...request.callbackUrl && { callbackUrl: request.callbackUrl },
+      ...request.idempotencyKey && { idempotencyKey: request.idempotencyKey }
+    };
+    const encryptedPayload = this.encrypt(withdrawalData);
+    const headers = {
+      "x-encrypted": "true"
+    };
+    if (request.idempotencyKey) {
+      headers["Idempotency-Key"] = request.idempotencyKey;
+    }
+    const response = await this.request("/withdraw", {
       method: "POST",
-      headers: {
-        "x-encrypted": "true"
-      },
+      headers,
       body: JSON.stringify(encryptedPayload)
     });
+    response.withdrawalId = response.id;
+    return response;
+  }
+  /**
+   * Get withdrawal status by ID, external ID, or reference
+   */
+  async getWithdrawalStatus(withdrawalId) {
+    if (!withdrawalId) throw new Error("withdrawalId is required");
+    return await this.request(`/withdraw/${withdrawalId}`, {
+      method: "GET"
+    });
+  }
+  /**
+   * Poll until withdrawal reaches a terminal status (paid, rejected, or failed)
+   */
+  async waitForWithdrawalCompletion(withdrawalId, options) {
+    const maxAttempts = options?.maxAttempts || 60;
+    const interval = options?.interval || 3e3;
+    let attempts = 0;
+    while (attempts < maxAttempts) {
+      attempts++;
+      const status = await this.getWithdrawalStatus(withdrawalId);
+      options?.onProgress?.(attempts, status.status);
+      if (status.status === "paid" || status.status === "rejected" || status.status === "failed") {
+        return status;
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    throw new Error("Withdrawal timeout - still processing after maximum attempts");
   }
   /**
    * List withdrawals
@@ -186,7 +229,7 @@ var PataLinkClient = class {
     if (options?.limit) params.append("limit", options.limit.toString());
     if (options?.offset) params.append("offset", options.offset.toString());
     const query = params.toString();
-    const endpoint = `/api/withdrawals${query ? `?${query}` : ""}`;
+    const endpoint = `/withdrawals${query ? `?${query}` : ""}`;
     return this.request(endpoint, { method: "GET" });
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patalink/node-api-client",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Official PataLink API client - Simple, secure payment integration",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -12,7 +12,9 @@
       "require": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "test": "jest",
@@ -40,4 +42,4 @@
   "dependencies": {
     "crypto-js": "^4.2.0"
   }
-}
+}