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

``bash
npm install bnksy-sdk
`

Quick Start

`javascript
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

$3

`javascript
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);
`

$3

`javascript
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: 'philip@email.com',
customerPhone: '11998589706',
externalClientId: 'YOUR-REFERENCE-ID',
details: {
documentNumber: '54944801009', // CPF
birthday: '1990-01-01',
orderNumber: '212912'
}
});

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

$3

Accept USD/EUR and receive crypto:

`javascript
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

`javascript
// 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.

$3

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

`javascript
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

`javascript
// 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:

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

`javascript
// 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:

`javascript
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

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

#### Get Withdrawal History

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

---

$3

Send BRL via PIX to recipients in Brazil:

`javascript
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 });
`

---

$3

Send money to a bank account:

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

---

$3

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

`javascript
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

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

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

---

API Reference

$3

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

$3

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

$3

Requires private key - transactions are signed client-side.

`javascript
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 |

$3

`javascript
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 |

$3

Requires private key for crypto delivery.

`javascript
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 |

$3

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

$3

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

$3

`javascript
// 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!

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