Complete SDK for Banksy payments - Crypto, PIX, Fiat-to-Crypto, and Payouts
npm install bnksy-sdkComplete SDK for integrating Banksy payments into your application.
- 🪙 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
``bash`
npm install bnksy-sdk
`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);
`
`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);
`
`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);
`
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'
});
`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
});
`
---
Send money out from your platform to recipients.
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'
});
---
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 });
`
---
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'
}
});
---
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'
});
`
---
`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();
`
`javascript`
try {
const payment = await banksy.createPayment({...});
} catch (error) {
console.error('Payment failed:', error.message);
}
---
`javascript`
new BanksySDK({
apiKey: string, // Required: Your API key
serverUrl?: string, // Optional: Server URL (default: https://api.mumadd.com)
})
| 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 |
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 |
`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 |
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 |
| Method | Description |
|--------|-------------|
| createBankWithdraw(options) | Create bank withdrawal |
| Method | Description |
|--------|-------------|
| checkStatus() | Check API status |getProviders()
| | Get available providers |getContracts()
| | Get crypto contracts |getKeyInfo()
| | Get API key info |
---
| Blockchain | blockchainName | Native Token | Stablecoins |eth
|------------|------------------|--------------|-------------|
| Ethereum | | ETH | USDT, USDC |bsc
| BSC | | BNB | USDT, USDC |matic
| Polygon | | MATIC | USDT, USDC |tron
| TRON | | TRON | USDT |btc
| Bitcoin | | BTC | - |
`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
`
---
⚠️ 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'
});
``
MIT