@fiddupay/fiddupay-node

v2.6.1

Published

3 days ago

FidduPay payment gateway Node.js SDK

0High
0Medium
0Low

techytro

fiddupay cryptocurrency payments blockchain bitcoin ethereum solana usdt fintech api

FidduPay Node.js SDK v2.6.0

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

// 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

npm install @fiddupay/fiddupay-node

Basic Usage

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

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

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

Retrieve Payment

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

List Payments

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

Cancel Payment

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

Verify Payment

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

Webhook Handling

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

// 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

// 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

// Create an invoice
const invoice = await client.invoices.create({
  customer_email: '[email protected]',
  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

// 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

// Register a customer
const customer = await client.customers.register({
  external_id: 'user_123',
  email: '[email protected]'
});

// 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

// 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

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

Error Handling

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

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

Fork the repository
Create a feature branch: git checkout -b feature/new-feature
Commit changes: git commit -am 'Add new feature'
Push to branch: git push origin feature/new-feature
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Documentation: https://fiddupay.com/docs
Issues: GitHub Issues
Email: [email protected]

Made with care by the FidduPay Team