bnksy-sdk

/** * Banksy Payment SDK * * Complete SDK for integrating Banksy payments: * - Crypto payments (ETH, USDT, USDC, BNB, etc.) * - PIX payments (Brazil) * - Fiat-to-Crypto conversions * - Crypto payouts * - Withdrawals */ interface BanksySDKConfig { /** Client's API key (clientKey or clientSecret from dashboard) */ apiKey: string; /** Banksy server URL */ serverUrl?: string; } type PaymentProvider = 'crypto' | 'pix' | 'fiat' | 'sumup' | 'payid' | 'manual'; type PaymentStatus = 'pending' | 'processing' | 'success' | 'failed' | 'expired' | 'refunded'; type CryptoToken = 'ETH' | 'USDT' | 'USDC' | 'BNB' | 'POL' | 'TRX' | 'BTC'; type Blockchain = 'eth' | 'bsc' | 'pol' | 'trx' | 'btc'; interface CryptoDetails { tokenName: CryptoToken; blockchainName: Blockchain; } interface CreatePaymentOptions { /** Amount in the payment currency */ amount?: number; /** Currency code (e.g., 'BRL', 'USD', 'EUR') - for fiat payments */ currency?: string; /** Crypto payment details - for crypto payments */ crypto?: CryptoDetails; /** Fiat amount for fiat-to-crypto conversion */ fiatAmount?: number; /** Fiat currency for conversion (USD, EUR, GBP, etc.) */ fiatCurrency?: 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF'; /** Success callback URL */ successCallback: string; /** Failure callback URL */ failureCallback: string; /** Your internal reference ID */ externalClientId?: string; /** Additional context data */ context?: Record<string, any>; /** Customer name (required for PIX) */ customerName?: string; /** Customer email (required for PIX) */ customerEmail?: string; /** Customer phone (required for PIX) */ customerPhone?: string; /** Additional details for PIX payments */ details?: { /** Customer document number (CPF for Brazil) */ documentNumber?: string; /** Customer birthday (YYYY-MM-DD) */ birthday?: string; /** Order number */ orderNumber?: string; }; } interface Payment { _id: string; paymentId?: string; amount: number; currency: string; status: PaymentStatus; provider: PaymentProvider; externalClientId?: string; address?: string; qrCode?: string; pixCode?: string; createdAt: string; updatedAt: string; expiry?: string; txHash?: string; context?: Record<string, any>; } interface PaymentResponse { success: boolean; payment?: Payment; message?: string; error?: string; } interface CreateWithdrawOptions { /** Amount to withdraw */ amount: number; /** Currency */ currency: string; /** Recipient wallet address (for crypto) */ address?: string; /** Bank details (for fiat) */ bankDetails?: { accountNumber: string; accountName: string; bankCode: string; }; } interface Withdraw { _id: string; amount: number; currency: string; status: string; address?: string; txHash?: string; createdAt: string; } interface CryptoPayoutConfig { /** Private key for signing transactions */ privateKey: string; } interface PayoutResult { success: boolean; payoutId?: string; txHash: string; grossAmount: string; feeAmount: string; netAmount: string; recipient: string; gasUsed?: string; } interface BatchPayoutResult { success: boolean; payoutIds: string[]; txHash: string; totalGross: string; totalFees: string; totalNet: string; gasUsed?: string; } interface ClientStatus { isActive: boolean; feeBasisPoints: number; feePercentage: string; walletAddress: string; } interface BalanceInfo { usdtBalance: string; ethBalance: string; allowance: string; canPayout: boolean; } interface TransactionRequest { to: string; data: string; value: string; gasLimit: string; chainId: number; nonce: number; maxFeePerGas?: string; maxPriorityFeePerGas?: string; } type PixKeyType = 'CPF' | 'EMAIL' | 'PHONE' | 'EVP'; type PixPayoutStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'refunded'; interface PixPayoutRecipient { /** Recipient's full name */ name: string; /** Recipient's CPF document number */ document: string; /** Recipient's birthday (YYYY-MM-DD) - optional */ birthday?: string; } interface CreatePixPayoutOptions { /** Amount in BRL to send */ amount: number; /** PIX key (CPF, email, phone, or random key) */ pixKey: string; /** Type of PIX key */ pixKeyType: PixKeyType; /** Recipient information */ recipient: PixPayoutRecipient; /** Your internal reference ID */ reference?: string; } interface PixPayout { payoutId: string; reference: string; amount: number; currency: string; status: PixPayoutStatus; recipient: { name: string; pixKey: string; pixKeyType: PixKeyType; }; createdAt: string; updatedAt?: string; completedAt?: string; } interface PixPayoutBalance { available: number; currency: string; } type FiatCurrency = 'USD' | 'EUR' | 'GBP' | 'BRL' | 'INR' | 'AUD' | 'CAD' | 'JPY' | 'CNY' | 'MXN'; type FiatCryptoPayoutStatus = 'pending' | 'converting' | 'processing' | 'completed' | 'failed' | 'cancelled'; interface ExchangeRate { rate: number; fiatCurrency: string; cryptoToken: string; timestamp: string; source: string; } interface FiatCryptoQuote { fiat: { amount: number; currency: string; }; crypto: { grossAmount: string; token: string; network: string; }; fees: { platformFeeBasisPoints: number; platformFeePercent: string; platformFeeAmount: string; }; netAmount: string; exchangeRate: { rate: number; timestamp: string; source: string; }; validFor: string; expiresAt: string; } interface CreateFiatCryptoPayoutOptions { /** Client wallet address (payer) */ wallet: string; /** Recipient wallet address */ recipient: string; /** Amount in fiat currency */ fiatAmount: number; /** Fiat currency code */ fiatCurrency?: FiatCurrency; /** Target crypto token (default: USDT) */ cryptoToken?: 'USDT'; /** Your internal reference */ reference?: string; /** Additional metadata */ metadata?: Record<string, any>; } interface FiatCryptoPayout { payoutId: string; status: FiatCryptoPayoutStatus; clientWallet: string; recipientWallet: string; fiat: { amount: number; currency: string; }; crypto: { grossAmount: string; token: string; network: string; }; fees: { platformFeeBasisPoints: number; platformFeeAmount: string; }; netAmount: string; exchangeRate: { rate: number; timestamp: string; source: string; }; transaction?: { txHash: string; payoutId: string; gasUsed: string; blockNumber: number; confirmedAt: string; }; reference: string; createdAt: string; updatedAt: string; } interface SupportedCurrencies { fiatCurrencies: Array<{ code: string; name: string; }>; cryptoTokens: string[]; networks: string[]; } interface Provider { name: string; type: string; currencies: string[]; enabled: boolean; } interface Contract { name: string; symbol: string; address: string; blockchain: string; decimals: number; } declare class BanksySDK { private apiKey; private serverUrl; cryptoPayout: CryptoPayoutModule | null; pixPayout: PixPayoutModule; fiatCryptoPayout: FiatCryptoPayoutModule; constructor(config: BanksySDKConfig); /** * Create a new payment * Supports: Crypto, PIX, Fiat-to-Crypto */ createPayment(options: CreatePaymentOptions): Promise<PaymentResponse>; /** * Get payment by ID */ getPayment(paymentId: string): Promise<Payment>; /** * Get payment status */ getPaymentStatus(paymentId: string): Promise<{ status: PaymentStatus; payment: Payment; }>; /** * Get multiple payments by IDs */ getPayments(ids: string[]): Promise<Payment[]>; /** * Get all payments with pagination */ getAllPayments(options?: { status?: PaymentStatus; skip?: number; limit?: number; }): Promise<{ payments: Payment[]; total: number; }>; /** * Verify a payment (mark as verified) */ verifyPayment(paymentId: string): Promise<Payment>; /** * Confirm a payment manually */ confirmPayment(paymentId: string, options?: { utr?: string; url?: string; }): Promise<Payment>; /** * Create a refund for a payment */ createRefund(paymentId: string, options?: { amount?: number; reason?: string; }): Promise<any>; /** * Create a crypto withdrawal */ createWithdraw(options: CreateWithdrawOptions): Promise<Withdraw>; /** * Create a bank withdrawal */ createBankWithdraw(options: CreateWithdrawOptions): Promise<Withdraw>; /** * Check API status */ checkStatus(): Promise<{ status: string; }>; /** * Get available payment providers */ getProviders(): Promise<Provider[]>; /** * Get supported crypto contracts */ getContracts(): Promise<Contract[]>; /** * Get API key info */ getKeyInfo(): Promise<any>; /** * Initialize crypto payout module * Required for processing payouts via PayoutProcessor contract */ initCryptoPayout(config: CryptoPayoutConfig): CryptoPayoutModule; /** * Make authenticated request to Banksy server */ request<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: any): Promise<T>; /** * Get server URL (for sub-modules) */ getServerUrl(): string; /** * Get API key (for sub-modules) */ getApiKey(): string; } declare class CryptoPayoutModule { private sdk; private wallet; private network; constructor(sdk: BanksySDK, config: CryptoPayoutConfig); /** * Get client registration status */ getClientStatus(): Promise<ClientStatus>; /** * Get wallet balances */ getBalanceInfo(): Promise<BalanceInfo>; /** * Check if contract is paused */ isPaused(): Promise<boolean>; /** * Calculate payout breakdown */ calculatePayout(amount: string): Promise<{ grossAmount: string; fee: string; net: string; feeBasisPoints: number; }>; /** * Check if approval is needed */ needsApproval(amount: string): Promise<boolean>; /** * Approve USDT spending */ approve(amount: string): Promise<string>; /** * Process a single payout */ processPayout(recipient: string, amount: string, reference?: string): Promise<PayoutResult>; /** * Process batch payouts */ processPayoutsBatch(payouts: Array<{ recipient: string; amount: string; reference?: string; }>): Promise<BatchPayoutResult>; /** * Estimate gas for payout */ estimateGas(recipient: string, amount: string): Promise<{ gasLimit: string; gasPrice: string; estimatedCostWei: string; estimatedCostEth: string; }>; /** * Get wallet address */ getAddress(): string; /** * Get network */ getNetwork(): string; private request; private signAndBroadcast; private preflight; } declare class PixPayoutModule { private sdk; constructor(sdk: BanksySDK); /** * Create a PIX payout (send money to recipient in Brazil) */ create(options: CreatePixPayoutOptions): Promise<PixPayout>; /** * Get payout by ID */ get(payoutId: string): Promise<PixPayout>; /** * Get payout status */ getStatus(payoutId: string): Promise<{ payoutId: string; status: PixPayoutStatus; providerStatus?: number; }>; /** * List payouts with pagination */ list(options?: { status?: PixPayoutStatus; skip?: number; limit?: number; }): Promise<{ payouts: PixPayout[]; total: number; hasMore: boolean; }>; /** * Get StarsPay account balance */ getBalance(): Promise<PixPayoutBalance>; /** * Validate a CPF document */ validateCPF(cpf: string): Promise<{ valid: boolean; status?: string; message?: string; }>; } declare class FiatCryptoPayoutModule { private sdk; private network; constructor(sdk: BanksySDK); /** * Get supported fiat currencies */ getSupportedCurrencies(): Promise<SupportedCurrencies>; /** * Get current exchange rate */ getExchangeRate(fiatCurrency?: FiatCurrency, cryptoToken?: string): Promise<ExchangeRate>; /** * Get a quote for fiat-to-crypto payout (preview before creating) */ getQuote(options: { wallet: string; fiatAmount: number; fiatCurrency?: FiatCurrency; cryptoToken?: string; }): Promise<{ quote: FiatCryptoQuote; }>; /** * Create a fiat-to-crypto payout * Step 1: Creates payout record and locks in exchange rate */ create(options: CreateFiatCryptoPayoutOptions): Promise<FiatCryptoPayout>; /** * Prepare payout transaction for signing * Step 2: Gets transaction data after payout is created */ prepare(payoutId: string, wallet: string): Promise<{ payoutId: string; transaction: TransactionRequest; payout: { fiat: { amount: number; currency: string; }; crypto: { grossAmount: string; token: string; network: string; }; recipient: string; netAmount: string; }; }>; /** * Confirm payout after transaction is broadcasted * Step 3: Confirms the payout with transaction hash */ confirm(payoutId: string, txHash: string): Promise<FiatCryptoPayout>; /** * Get payout by ID */ get(payoutId: string): Promise<FiatCryptoPayout>; /** * List payouts with pagination */ list(options?: { page?: number; limit?: number; status?: FiatCryptoPayoutStatus; fiatCurrency?: FiatCurrency; wallet?: string; startDate?: string; endDate?: string; }): Promise<{ payouts: FiatCryptoPayout[]; pagination: { page: number; limit: number; total: number; pages: number; }; }>; /** * Cancel a pending payout */ cancel(payoutId: string): Promise<{ payoutId: string; status: string; }>; /** * Get current network */ getNetwork(): string; private request; } declare function createBanksySDK(config: BanksySDKConfig): BanksySDK; export { type BalanceInfo, BanksySDK, type BanksySDKConfig, type BatchPayoutResult, type Blockchain, type ClientStatus, type Contract, type CreateFiatCryptoPayoutOptions, type CreatePaymentOptions, type CreatePixPayoutOptions, type CreateWithdrawOptions, type CryptoDetails, type CryptoPayoutConfig, CryptoPayoutModule, type CryptoToken, type ExchangeRate, type FiatCryptoPayout, FiatCryptoPayoutModule, type FiatCryptoPayoutStatus, type FiatCryptoQuote, type FiatCurrency, type Payment, type PaymentProvider, type PaymentResponse, type PaymentStatus, type PayoutResult, type PixKeyType, type PixPayout, type PixPayoutBalance, PixPayoutModule, type PixPayoutRecipient, type PixPayoutStatus, type Provider, type SupportedCurrencies, type TransactionRequest, type Withdraw, createBanksySDK, BanksySDK as default };