npm package: @fiddupay/fiddupay-node
Description: FidduPay payment gateway Node.js SDK
Author: TechyTro Software
Latest version: 2.6.1

# FidduPay Node.js SDK v2.6.0

[![version](https://img.shields.io/badge/version-v2.6.0-blue.svg?style=flat-square)](https://github.com/fiddupay/fiddupay-node)
[![npm downloads](https://img.shields.io/npm/dm/@fiddupay/fiddupay-node.svg?style=flat-square)](https://www.npmjs.com/package/@fiddupay/fiddupay-node)
[![Build Status](https://github.com/fiddupay/fiddupay-node/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/fiddupay/fiddupay-node/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official Node.js SDK for the FidduPay cryptocurrency payment gateway platform with **2-Mode Wallet System**.

## Daily Volume Limits

- **Non-KYC Merchants**: $100,000 USD daily volume limit (combined deposits + withdrawals)
- **KYC Verified Merchants**: No daily volume limits
- **Reset**: Daily limits reset at midnight UTC
- **Tracking**: Real-time volume tracking across all transaction types

```typescript
// Check your daily volume status
const profile = await client.merchants.retrieve();
console.log('KYC Status:', profile.kyc_verified);
console.log('Daily Volume Remaining:', profile.daily_volume_remaining);
```

## 2-Mode Wallet System

FidduPay offers two flexible wallet modes to suit different merchant needs:

### Mode 1: Generate Keys (Fully Managed)
FidduPay generates and manages wallet keys for you. Perfect for merchants who want a hands-off approach.

### Mode 2: Address-Only (Forwarding)
Customers pay directly from their own wallets to your addresses. No key management or private keys generated by FidduPay.

## Quick Start

### Installation

```bash
npm install @fiddupay/fiddupay-node
```

### Basic Usage

```typescript
import { FidduPayClient } from '@fiddupay/fiddupay-node';

const client = new FidduPayClient({
  apiKey: 'sk_sandbox_your_api_key',
  environment: 'sandbox' // or 'production'
});

// Create a payment
const payment = await client.payments.create({
  amount_usd: '100.50',
  crypto_type: 'ETH',
  description: 'Order #12345'
});

console.log('Payment created:', payment.id);

// Sandbox Simulation (in sandbox environment)
await client.sandbox.simulatePayment(payment.id, {
  success: true,
  transaction_hash: '0xabc...',
  from_address: '0xsender...'
});
```

## Features

- **Payment Processing**: Create, retrieve, list, and cancel payments
- **Webhook Verification**: Secure HMAC-SHA256 signature validation
- **Merchant Management**: Profile, balance, and wallet configuration
- **Refund Operations**: Create and track refunds
- **Analytics**: Data retrieval and export
- **Security**: Input validation, rate limiting, retry logic
- **TypeScript**: Full type definitions included
- **Daily Volume Limits**: KYC status and volume tracking support

## Configuration

```typescript
const client = new FidduPayClient({
  apiKey: 'sk_sandbox_your_api_key',
  environment: 'sandbox', // 'sandbox' or 'production'
  timeout: 30000, // Request timeout in milliseconds
  retries: 3, // Number of retry attempts
  baseURL: 'https://api.fiddupay.com' // Custom API base URL
});
```

## Payment Operations

### Create Payment

```typescript
const payment = await client.payments.create({
  amount_usd: '100.50',
  crypto_type: 'ETH',
  description: 'Order #12345',
  metadata: {
    orderId: '12345',
    customerId: 'cust_123'
  }
});
```

### Retrieve Payment

```typescript
const payment = await client.payments.retrieve('pay_123');
```

### List Payments

```typescript
const payments = await client.payments.list({
  page: 1,
  page_size: 10,
  status: 'completed'
});
```

### Cancel Payment

```typescript
await client.payments.cancel('pay_123');
```

### Verify Payment

```typescript
// Trigger instant validation for transaction hash
const isConfirmed = await client.payments.verify('pay_123', '0xabc123...');
console.log('Payment confirmed:', isConfirmed);
```

## Webhook Handling

```typescript
import express from 'express';
import { Webhooks } from '@fiddupay/fiddupay-node';

const app = express();

app.post('/webhooks/fiddupay', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['fiddupay-signature'] as string;
  
  try {
    const event = Webhooks.constructEvent(
      req.body,
      signature,
      'your-webhook-secret'
    );

    switch (event.type) {
      case 'payment.detected':
        console.log('Payment detected (0-conf):', event.data);
        break;
      case 'payment.partially_paid':
        console.log('Partial payment received:', event.data);
        break;
      case 'payment.confirmed':
        console.log('Payment confirmed:', event.data);
        break;
      case 'payment.failed':
        console.log('Payment failed:', event.data);
        break;
      case 'merchant.deposit':
        console.log('Merchant static deposit confirmed:', event.data);
        break;
      case 'customer.deposit':
        console.log('Customer static deposit confirmed:', event.data);
        break;
      case 'address_only_payment_status':
        console.log('Address-only payment status update:', event.data);
        break;
      case 'webhook.test':
        console.log('Test webhook successful:', event.data);
        break;
      case 'wallet.low_balance':
          console.log('Low gas wallet balance:', event.data);
          break;
    }

    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(400).send('Invalid signature');
  }
});
```

## Merchant Operations

```typescript
// Get merchant profile (includes KYC status and daily volume)
const profile = await client.merchants.retrieve();
console.log('KYC Verified:', profile.kyc_verified);
console.log('Daily Volume Remaining:', profile.daily_volume_remaining);

// Get account balance
const balance = await client.merchants.getBalance();
console.log('Total USD:', balance.total_usd);
balance.balances.forEach(b => {
  console.log(`${b.crypto_type}: ${b.available} (Available), ${b.total} (Total)`);
});

// Configure wallet (Unified Setup)
await client.wallets.setup({
  crypto_type: 'ETH',
  mode: 'address',
  address: '0x742d35Cc6634C0532925a3b8D4C9db96590c6C87',
  is_active: true
});

// Wallet Security locks (New in v2.4.6)
await client.security.toggleWalletLock(true); // Lock master wallets
await client.security.toggleCustomerWalletLock(true); // Lock customer wallets

// PIN Management (New in v2.5.6)
await client.security.setTransactionPin('1234'); // Set a new PIN
const isPinValid = await client.security.verifyTransactionPin('1234'); // Verify PIN


```

## Refund Operations

```typescript
// Create refund
const refund = await client.refunds.create({
  paymentId: 'pay_123',
  amount: '50.25',
  reason: 'customer_request'
});

// List refunds
const refunds = await client.refunds.list({
  paymentId: 'pay_123'
});
```

## Invoice Operations

```typescript
// Create an invoice
const invoice = await client.invoices.create({
  customer_email: 'client@example.com',
  customer_name: 'John Doe',
  items: [
    {
      description: 'Consulting services',
      quantity: 1,
      unit_price: '150.00',
      amount: '150.00'
    }
  ],
  tax: '0.00',
  notes: 'Payment due within 30 days'
});

// List invoices
const invoices = await client.invoices.list();

// Retrieve invoice details
const invoiceDetails = await client.invoices.retrieve(invoice.invoice_id);
```

## Withdrawal Operations

```typescript
// Create a withdrawal request (Managed Mode only)
const withdrawal = await client.withdrawals.create({
  amount: '50.0',
  crypto_type: 'SOL',
  destination_address: '8xH9...',
  pin: '1234' // Merchant's 4-digit Transaction PIN
});

// List withdrawals
const withdrawals = await client.withdrawals.list({
  limit: 10
});

// Cancel a pending withdrawal
await client.withdrawals.cancel('wd_123');
```

## Customer Management

```typescript
// Register a customer
const customer = await client.customers.register({
  external_id: 'user_123',
  email: 'user@example.com'
});

// Fetch aggregate summary of all platform customers (New in v2.6.0)
const summary = await client.customers.getSummary();
console.log(`Total Aggregate Customer Balance: $${summary.total_balance_usd}`);

// Provision wallets
// Note: Deposits into these wallets ONLY affect individual customer sub-balances.
// They do NOT credit the merchant master balance directly.
await client.customers.createWallets('user_123', {
  networks: ['evm', 'solana']
});

// Update permissions (New in v2.4.6)
await client.customers.updatePermissions('user_123', {
  can_withdraw: true,
  withdrawal_limit: '500.0'
});

// Get customer deposit address
const addrObj = await client.customers.getDepositAddress('user_123', 'SOL');
console.log('Deposit address:', addrObj.address);

// Lock funds into merchant reserved balance (Customer Initiated Workflow)
await client.customers.payMerchant('user_123', {
  crypto_type: 'SOL',
  amount: '1.0',
  reference_id: 'order_123'
});

// Sweep ALL assets to your Master Wallet (Non-Custodial)
await client.customers.sweep('user_123', {
  sweep_mode: 'ALL',
  pin: '1234' // Merchant's 4-digit Transaction PIN
});

// Sweep only stablecoins
await client.customers.sweep('user_123', {
  sweep_mode: 'STABLE_ONLY',
  pin: '1234'
});

// Sweep only native coins (ETH, BNB, SOL, etc.)
await client.customers.sweep('user_123', {
  sweep_mode: 'NATIVE_ONLY',
  pin: '1234'
});

// Sweep a specific asset (optionally cap the amount)
await client.customers.sweep('user_123', {
  sweep_mode: 'SPECIFIC',
  crypto_types: ['USDT_ETH'],
  amount: '50.0',   // optional, omit to sweep max
  pin: '1234'
});

// Get customer wallets
const wallets = await client.customers.getWallets('user_123');
console.log('Wallets:', wallets);

// NEW in v2.5.5: Bulk provision wallets for selected customers
await client.customers.bulkProvision({
  customer_ids: ['user_123', 'user_456']
});

// NEW in v2.5.5: Bulk provision wallets for ALL customers
await client.customers.bulkProvision({
  all_customers: true
});
```

> **Non-Custodial Sweep Architecture (v2.5.8+)**
>
> `sweep()` replaces the deprecated `withdraw()`. Funds stay locked in the
> customer sub-wallet until the merchant explicitly triggers a sweep to their
> own Master Wallet. Gas fees for EVM sweeps are **auto-funded from the
> merchant's native ledger** — customers never see gas-funding transactions.



## Analytics

```typescript
// Get analytics data
const analytics = await client.analytics.retrieve({
  from_date: '2026-01-01',
  to_date: '2026-01-31',
  granularity: 'day'
});

// Export data
const exportData = await client.analytics.export({
  format: 'csv',
  from_date: '2026-01-01',
  to_date: '2026-01-31'
});
```

## Universal Transactions Feed

```typescript
// List unified cross-resource transactions feed (Payments, Withdrawals, Refunds)
const feed = await client.transactions.list({
  limit: 20
});
```

## Error Handling

```typescript
import { FidduPayError, APIError, AuthenticationError, ValidationError, RateLimitError } from '@fiddupay/fiddupay-node';

try {
  const payment = await client.payments.create({
    amount_usd: '100',
    crypto_type: 'ETH'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('Invalid parameters:', error.details);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded, retry after:', error.retryAfter);
  } else if (error instanceof APIError) {
    console.error('API error:', error.message);
  }
}
```

## Security

- **API Key Security**: Never expose API keys in client-side code
- **Webhook Verification**: Always verify webhook signatures
- **HTTPS Only**: All API calls use HTTPS encryption
- **Input Validation**: All inputs are validated and sanitized

## Supported Cryptocurrencies

**6 Major Blockchain Networks:**
- **Bitcoin** - BTC (SegWit)
- **Solana** - SOL + USDT (SPL)
- **Ethereum** - ETH + USDT (ERC-20)
- **Binance Smart Chain** - BNB + USDT (BINANCE) + BUSD (BINANCE)
- **Polygon** - MATIC + USDT
- **Arbitrum** - ARB + USDT

**Total: 12 cryptocurrency options across 6 blockchains**

## Postman Documentation

The SDK includes a dedicated Postman collection for merchant integration:
`postman/FidduPay-Merchant-API.postman_collection.json`


## API Reference

For complete API documentation, visit: [https://fiddupay.com/docs](https://fiddupay.com/docs)

## Complete API Method Index

Grouped by `client.*` resource modules for reference:

| Module | Methods |
| :--- | :--- |
| **`merchants`** | `register()`, `retrieve()`, `getStatus()`, `getReadiness()`, `switchEnvironment()`, `generateApiKey()`, `rotateApiKey()`, `getFeeSetting()`, `updateSettings()`, `getSettings()`, `sendTestWebhook()`, `getIpWhitelist()`, `getBalance()`, `getAuditLogs()`, `getBalanceHistory()` |
| **`payments`** | `create()`, `retrieve()`, `list()`, `cancel()`, `verify()`, `finalizeSelection()`, `simulate()`, `getAnalytics()`, `updateFeeSetting()`, `getFeeSetting()` |
| **`addressOnly`** | `create()`, `retrieve()`, `listCurrencies()`, `getStats()`, `getHealth()`, `getFeeSetting()`, `setFeeSetting()` |
| **`wallets`** | `setup()`, `getConfigurations()`, `getBalances()`, `getGasEstimates()`, `checkGasRequirements()`, `gasCheck()`, `checkWithdrawalCapability()`, `revoke()` |
| **`balances`** | `get()`, `getHistory()` |
| **`auditLogs`** | `list()` |
| **`customers`** | `register()`, `createWallets()`, `getWallets()`, `getBalances()`, `list()`, `sweep(sweep_mode)`, `deactivate()`, `getTransactions()`, `updateStatus()`, `updatePermissions()`, `getDepositAddress()`, `payMerchant()`, `bulkProvision()`, `getSummary()` |
| **`withdrawals`** | `create()`, `list()`, `get()`, `cancel()` |
| **`refunds`** | `create()`, `list()`, `retrieve()`, `complete()` |
| **`invoices`** | `create()`, `list()`, `retrieve()` |
| **`transactions`** | `list()` |
| **`analytics`** | `retrieve()`, `export()`, `getUnifiedTransactions()` |
| **`security`** | `getEvents()`, `getAlerts()`, `getSettings()`, `updateSettings()`, `checkGasBalances()`, `getBalanceAlerts()`, `acknowledgeAlert()`, `resolveBalanceAlert()`, `toggleWalletLock()`, `toggleCustomerWalletLock()`, `setTransactionPin()`, `verifyTransactionPin()` |

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-feature`
3. Commit changes: `git commit -am 'Add new feature'`
4. Push to branch: `git push origin feature/new-feature`
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- **Documentation**: [https://fiddupay.com/docs](https://fiddupay.com/docs)
- **Issues**: [GitHub Issues](https://github.com/fiddupay/fiddupay-node/issues)
- **Email**: techytrosoftware@gmail.com

---

**Made with care by the FidduPay Team**