bnksy-sdk

Complete SDK for integrating Banksy payments into your application.

Features

• 🪙 Crypto Payments - Accept ETH, USDT, USDC, BNB, MATIC, TRON, BTC
• 💵 PIX Payments - Accept PIX payments (Brazil)
• 🔄 Fiat-to-Crypto - Accept fiat and convert to crypto automatically
• 💸 Withdrawals - Process withdrawals via smart contract, PIX, or bank transfer

Installation

npm install bnksy-sdk

Quick Start

import { BanksySDK } from 'bnksy-sdk';

const banksy = new BanksySDK({
  apiKey: 'your-api-key' // clientKey or clientSecret from dashboard
});

// Check connection
const status = await banksy.checkStatus();
console.log('Connected:', status);

Creating Payments

Crypto Payment

const payment = await banksy.createPayment({
  amount: 100, // 100 USDT
  crypto: {
    tokenName: 'USDT',
    blockchainName: 'eth'
  },
  successCallback: 'https://yoursite.com/success',
  failureCallback: 'https://yoursite.com/failure',
  externalClientId: 'order-123'
});

console.log('Payment address:', payment.payment.address);
console.log('QR Code:', payment.payment.qrCode);

PIX Payment (Brazil)

const payment = await banksy.createPayment({
  amount: 10,
  currency: 'BRL',
  successCallback: 'https://your-app.com/success',
  failureCallback: 'https://your-app.com/failure',
  customerName: 'Philip William',
  customerEmail: '[email protected]',
  customerPhone: '11998589706',
  externalClientId: 'YOUR-REFERENCE-ID',
  details: {
    documentNumber: '54944801009', // CPF
    birthday: '1990-01-01',
    orderNumber: '212912'
  }
});

console.log('PIX Code:', payment.payment.pixCode);

Fiat-to-Crypto Payment

Accept USD/EUR and receive crypto:

const payment = await banksy.createPayment({
  fiatAmount: 50,
  fiatCurrency: 'USD',
  crypto: {
    tokenName: 'USDT',
    blockchainName: 'eth'
  },
  successCallback: 'https://yoursite.com/success',
  failureCallback: 'https://yoursite.com/failure'
});

Checking Payment Status

// Get payment details
const payment = await banksy.getPayment('payment-id');
console.log('Status:', payment.status);

// Or just get status
const { status } = await banksy.getPaymentStatus('payment-id');

// Get multiple payments
const payments = await banksy.getPayments(['id1', 'id2', 'id3']);

// List all payments with pagination
const { payments, total } = await banksy.getAllPayments({
  status: 'success',
  skip: 0,
  limit: 10
});

Withdrawals

Send money out from your platform to recipients.

Crypto Withdrawals (Smart Contract)

Crypto withdrawals are processed via smart contract. Requires a private key to sign transactions client-side. This gives you full control and transparency over your funds.

Setup CryptoWithdrawModule

import { BanksySDK, CryptoWithdrawModule } from 'bnksy-sdk';

const banksy = new BanksySDK({
  apiKey: 'your-api-key'
});

// Initialize with your private key (KEEP THIS SECRET!)
const cryptoWithdraw = new CryptoWithdrawModule(banksy, {
  privateKey: process.env.WALLET_PRIVATE_KEY, // Required!
  network: 'mainnet' // or 'sepolia' for testing
});

// Check your wallet is properly configured
console.log('Wallet address:', cryptoWithdraw.getAddress());

Step 1: Check Balance & Approval

// Check your USDT balance
const balance = await cryptoWithdraw.getBalanceInfo();
console.log('USDT Balance:', balance.usdtBalance);
console.log('ETH for gas:', balance.ethBalance);

// Check if contract is approved to spend your USDT
const approval = await cryptoWithdraw.checkApproval();
console.log('Approved amount:', approval.allowance);

Step 2: Approve Contract (One-Time)

If not approved, you need to approve the contract first:

// Approve contract to spend your USDT (one-time setup)
const approvalResult = await cryptoWithdraw.approveContract('1000000'); // Max amount
console.log('Approval tx:', approvalResult.txHash);

Step 3: Process Withdrawal

// Single withdrawal - signs and broadcasts automatically
const result = await cryptoWithdraw.processWithdraw(
  '0xRecipientAddress...',  // Recipient wallet
  '100',                     // Amount in USDT
  'invoice-123'              // Your reference
);

console.log('Withdraw ID:', result.withdrawId);
console.log('Tx Hash:', result.txHash);
console.log('Net Amount:', result.netAmount); // After fees

Batch Withdrawals

Process multiple withdrawals in a single transaction:

const batchResult = await cryptoWithdraw.processWithdrawsBatch([
  { recipient: '0xAddress1...', amount: '100', reference: 'payout-1' },
  { recipient: '0xAddress2...', amount: '200', reference: 'payout-2' },
  { recipient: '0xAddress3...', amount: '50', reference: 'payout-3' }
]);

console.log('Batch tx:', batchResult.txHash);
console.log('Total processed:', batchResult.totalAmount);

Estimate Gas

const gas = await cryptoWithdraw.estimateGas(
  '0xRecipientAddress...',
  '100'
);
console.log('Estimated gas cost:', gas.estimatedCostEth, 'ETH');

Get Withdrawal History

const history = await cryptoWithdraw.getWithdrawHistory({
  skip: 0,
  limit: 20,
  status: 'success'
});

PIX Withdrawals (Brazil)

Send BRL via PIX to recipients in Brazil:

import { BanksySDK, PixWithdrawModule } from 'bnksy-sdk';

const pixWithdraw = new PixWithdrawModule(banksy);

// Check balance
const balance = await pixWithdraw.getBalance();

// Create PIX withdrawal
const withdrawal = await pixWithdraw.createWithdraw({
  amount: 100.00,
  pixKeyType: 'cpf',
  pixKey: '12345678900',
  recipient: {
    name: 'João Silva',
    document: '12345678900'
  },
  reference: 'payment-123'
});

console.log('Withdrawal ID:', withdrawal._id);
console.log('Status:', withdrawal.status);

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

Bank Withdrawals

Send money to a bank account:

const withdrawal = await banksy.createBankWithdraw({
  amount: 1000,
  currency: 'INR',
  context: {
    accountno: '1234567890',
    accountifsc: 'HDFC0001234',
    beneficiaryname: 'John Doe',
    beneficiarymobile: '9876543210'
  }
});

Fiat-to-Crypto Withdrawals

Convert fiat balances to crypto and withdraw. Requires a private key for crypto delivery.

import { BanksySDK, FiatCryptoWithdrawModule } from 'bnksy-sdk';

const fiatCryptoWithdraw = new FiatCryptoWithdrawModule(banksy, {
  privateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'mainnet'
});

// Get quote first
const quote = await fiatCryptoWithdraw.getQuote({
  fiatAmount: 1000,
  fiatCurrency: 'BRL',
  cryptoCurrency: 'USDT'
});
console.log('You will receive:', quote.cryptoAmount, 'USDT');

// Create and process withdrawal
const withdrawal = await fiatCryptoWithdraw.createAndProcess({
  fiatAmount: 1000,
  fiatCurrency: 'BRL',
  cryptoCurrency: 'USDT',
  blockchain: 'polygon',
  recipientAddress: '0xRecipientAddress...',
  reference: 'withdraw-123'
});

Utility Methods

// Get available providers
const providers = await banksy.getProviders();

// Get supported crypto contracts
const contracts = await banksy.getContracts();

// Get API key info
const keyInfo = await banksy.getKeyInfo();

Error Handling

try {
  const payment = await banksy.createPayment({...});
} catch (error) {
  console.error('Payment failed:', error.message);
}

API Reference

BanksySDK Constructor

new BanksySDK({
  apiKey: string,      // Required: Your API key
  serverUrl?: string,  // Optional: Server URL (default: https://api.mumadd.com)
})

Payment Methods

| Method | Description | |--------|-------------| | createPayment(options) | Create a new payment | | getPayment(id) | Get payment by ID | | getPaymentStatus(id) | Get payment status | | getPayments(ids) | Get multiple payments | | getAllPayments(options) | List payments with pagination | | verifyPayment(id) | Verify a payment | | confirmPayment(id, options) | Confirm payment manually |

CryptoWithdrawModule (Smart Contract)

Requires private key - transactions are signed client-side.

const cryptoWithdraw = new CryptoWithdrawModule(banksy, { 
  privateKey: 'YOUR_KEY', 
  network: 'mainnet' 
});

| Method | Description | |--------|-------------| | getStatus() | Get contract status | | getBalanceInfo() | Get USDT and ETH balance | | checkApproval() | Check contract approval | | approveContract(amount) | Approve contract to spend USDT | | processWithdraw(recipient, amount, ref) | Process single withdrawal | | processWithdrawsBatch(payouts) | Process batch withdrawal | | estimateGas(recipient, amount) | Estimate gas cost | | getWithdrawHistory(options) | Get withdrawal history | | getAddress() | Get wallet address |

PixWithdrawModule (Brazil)

const pixWithdraw = new PixWithdrawModule(banksy);

| Method | Description | |--------|-------------| | getBalance() | Get StarsPay account balance | | createWithdraw(options) | Create PIX withdrawal | | getWithdraw(id) | Get withdrawal by ID | | getWithdrawStatus(id) | Get withdrawal status | | listWithdrawals(options) | List withdrawals | | validateCPF(cpf) | Validate CPF document |

FiatCryptoWithdrawModule

Requires private key for crypto delivery.

const fiatCryptoWithdraw = new FiatCryptoWithdrawModule(banksy, { 
  privateKey: 'YOUR_KEY', 
  network: 'mainnet' 
});

| Method | Description | |--------|-------------| | getSupportedCurrencies() | Get supported fiat currencies | | getExchangeRate(from, to) | Get current exchange rate | | getQuote(options) | Get withdrawal quote | | createWithdraw(options) | Create withdrawal | | createAndProcess(options) | Create and process in one call | | listWithdrawals(options) | List withdrawals |

Bank Withdrawal

| Method | Description | |--------|-------------| | createBankWithdraw(options) | Create bank withdrawal |

Utility Methods

| Method | Description | |--------|-------------| | checkStatus() | Check API status | | getProviders() | Get available providers | | getContracts() | Get crypto contracts | | getKeyInfo() | Get API key info |

Supported Tokens

| Blockchain | blockchainName | Native Token | Stablecoins | |------------|------------------|--------------|-------------| | Ethereum | eth | ETH | USDT, USDC | | BSC | bsc | BNB | USDT, USDC | | Polygon | matic | MATIC | USDT, USDC | | TRON | tron | TRON | USDT | | Bitcoin | btc | BTC | - |

Valid crypto Object Combinations

// Ethereum
{ tokenName: 'ETH', blockchainName: 'eth' }      // Native ETH
{ tokenName: 'USDT', blockchainName: 'eth' }     // USDT on Ethereum
{ tokenName: 'USDC', blockchainName: 'eth' }     // USDC on Ethereum

// BSC (Binance Smart Chain)
{ tokenName: 'BNB', blockchainName: 'bsc' }      // Native BNB
{ tokenName: 'USDT', blockchainName: 'bsc' }     // USDT on BSC
{ tokenName: 'USDC', blockchainName: 'bsc' }     // USDC on BSC

// Polygon
{ tokenName: 'MATIC', blockchainName: 'matic' }  // Native MATIC
{ tokenName: 'USDT', blockchainName: 'matic' }   // USDT on Polygon
{ tokenName: 'USDC', blockchainName: 'matic' }   // USDC on Polygon

// TRON
{ tokenName: 'TRON', blockchainName: 'tron' }    // Native TRON
{ tokenName: 'USDT', blockchainName: 'tron' }    // USDT on TRON (TRC-20)

// Bitcoin
{ tokenName: 'BTC', blockchainName: 'btc' }      // Native BTC

Security

⚠️ Never expose your API key or private key in client-side code!

// Use environment variables
const banksy = new BanksySDK({
  apiKey: process.env.BANKSY_API_KEY
});

const cryptoWithdraw = new CryptoWithdrawModule(banksy, {
  privateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'mainnet'
});

License

MIT