Package Exports
- @fiddupay/fiddupay-node
- @fiddupay/fiddupay-node/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@fiddupay/fiddupay-node) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
FidduPay Node.js SDK v2.5.3
Official Node.js SDK for the FidduPay cryptocurrency payment gateway platform with 2-Mode Wallet System.
Daily Volume Limits
- Non-KYC Merchants: $1,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-nodeBasic 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 '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
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: '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...'
});
// 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: 'user@example.com'
});
// Provision wallets
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);
// Pay merchant from sub-account balance
await client.customers.payMerchant('user_123', {
crypto_type: 'SOL',
amount: '1.0',
reference_id: 'order_123'
});
// Sweep funds to master wallet
await client.customers.sweep('user_123', {
crypto_type: 'USDT'
});
## 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
// 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 (BEP-20)
- Polygon - MATIC + USDT
- Arbitrum - ARB + USDT
Total: 11 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(), switchEnvironment(), generateApiKey(), rotateApiKey(), getFeeSetting(), updateSettings(), getSettings(), sendTestWebhook(), getIpWhitelist(), getBalance(), getAuditLogs(), getBalanceHistory() |
payments |
create(), retrieve(), list(), cancel(), verify(), finalizeSelection(), 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(), getBalances(), list(), withdraw(), sweep(), deactivate(), getTransactions(), updateStatus(), updatePermissions(), getDepositAddress(), payMerchant() |
withdrawals |
create(), list(), get(), cancel() |
refunds |
create(), list(), retrieve(), complete() |
invoices |
create(), list(), retrieve() |
transactions |
list() |
analytics |
retrieve(), export() |
security |
getEvents(), getAlerts(), getSettings(), updateSettings(), checkGasBalances(), getBalanceAlerts(), acknowledgeAlert(), resolveBalanceAlert(), toggleWalletLock(), toggleCustomerWalletLock() |
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: techytrosoftware@gmail.com
Made with care by the FidduPay Team