blaaiz-nodejs-sdk 1.0.0 → 1.0.2

package/README.md

@@ -13,12 +13,17 @@ npm install blaaiz-nodejs-sdk
 ```javascript
 const { Blaaiz } = require('blaaiz-nodejs-sdk');
 
-// Initialize the SDK
+// Initialize the SDK (defaults to development environment)
 const blaaiz = new Blaaiz('your-api-key-here', {
   baseURL: 'https://api-dev.blaaiz.com', // Optional: defaults to dev environment
   timeout: 30000 // Optional: request timeout in milliseconds
 });
 
+// For production, change the baseURL:
+// const blaaiz = new Blaaiz('your-prod-api-key', {
+//   baseURL: 'https://api.blaaiz.com'
+// });
+
 // Test the connection
 const isConnected = await blaaiz.testConnection();
 console.log('API Connected:', isConnected);
@@ -594,16 +599,55 @@ app.post('/webhooks/collection', (req, res) => {
 
 ## Environment Configuration
 
+The SDK defaults to the development environment. To use different environments:
+
 ```javascript
-// Development
+// Development (default)
+const blaaizDev = new Blaaiz('dev-api-key');
+// OR explicitly specify dev URL
 const blaaizDev = new Blaaiz('dev-api-key', {
   baseURL: 'https://api-dev.blaaiz.com'
 });
 
-// Production (when available)
+// Production
 const blaaizProd = new Blaaiz('prod-api-key', {
   baseURL: 'https://api.blaaiz.com'
 });
+
+// Staging (if available)
+const blaaizStaging = new Blaaiz('staging-api-key', {
+  baseURL: 'https://api-staging.blaaiz.com'
+});
+```
+
+### Environment Variables Approach (Recommended)
+
+```javascript
+const { Blaaiz } = require('blaaiz-nodejs-sdk');
+
+const blaaiz = new Blaaiz(process.env.BLAAIZ_API_KEY, {
+  baseURL: process.env.BLAAIZ_API_URL || 'https://api-dev.blaaiz.com'
+});
+```
+
+**Environment Variables:**
+- `BLAAIZ_API_KEY` - Your API key
+- `BLAAIZ_API_URL` - API base URL (optional, defaults to dev)
+- `BLAAIZ_WEBHOOK_SECRET` - Webhook secret for signature verification
+- `BLAAIZ_TEST_WALLET_ID` - Test wallet ID for integration tests (optional)
+
+**.env file example:**
+```bash
+# Development
+BLAAIZ_API_KEY=your-dev-api-key
+BLAAIZ_API_URL=https://api-dev.blaaiz.com
+BLAAIZ_WEBHOOK_SECRET=your-webhook-secret
+BLAAIZ_TEST_WALLET_ID=your-test-wallet-id
+
+# Production
+# BLAAIZ_API_KEY=your-prod-api-key
+# BLAAIZ_API_URL=https://api.blaaiz.com
+# BLAAIZ_WEBHOOK_SECRET=your-prod-webhook-secret
 ```
 
 ## Best Practices

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blaaiz-nodejs-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Official Node.js SDK for Blaaiz RaaS (Remittance as a Service) API",
   "main": "index.js",
   "types": "index.d.ts",
@@ -8,8 +8,10 @@
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "test:integration": "jest --testPathPattern=integration",
     "lint": "eslint src/**/*.js",
     "lint:fix": "eslint src/**/*.js --fix",
+    "audit": "npm audit --audit-level=moderate",
     "docs": "jsdoc -d docs src/**/*.js",
     "build": "npm run lint && npm test",
     "prepublishOnly": "npm run build"
@@ -55,11 +57,13 @@
     "eslint-plugin-n": "^15.7.0",
     "eslint-plugin-promise": "^6.1.1",
     "jest": "^29.5.0",
-    "jsdoc": "^4.0.2"
+    "jsdoc": "^4.0.2",
+    "audit-ci": "^7.0.1"
   },
   "files": [
     "index.js",
     "index.d.ts",
+    "src/",
     "README.md",
     "LICENSE"
   ],

package/src/client.js

@@ -0,0 +1,96 @@
+const https = require('https')
+const http = require('http')
+const { URL } = require('url')
+const BlaaizError = require('./error')
+
+class BlaaizAPIClient {
+  constructor (apiKey, options = {}) {
+    if (!apiKey) {
+      throw new Error('API key is required')
+    }
+
+    this.apiKey = apiKey
+    this.baseURL = options.baseURL || 'https://api-dev.blaaiz.com'
+    this.timeout = options.timeout || 30000
+    this.defaultHeaders = {
+      'x-blaaiz-api-key': this.apiKey,
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'User-Agent': 'Blaaiz-NodeJS-SDK/1.0.0'
+    }
+  }
+
+  async makeRequest (method, endpoint, data = null, headers = {}) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(endpoint, this.baseURL)
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: url.pathname + url.search,
+        method: method.toUpperCase(),
+        headers: { ...this.defaultHeaders, ...headers },
+        timeout: this.timeout
+      }
+
+      const client = url.protocol === 'https:' ? https : http
+      const req = client.request(options, (res) => {
+        let responseData = ''
+
+        res.on('data', (chunk) => {
+          responseData += chunk
+        })
+
+        res.on('end', () => {
+          try {
+            const parsedData = JSON.parse(responseData)
+
+            if (res.statusCode >= 200 && res.statusCode < 300) {
+              resolve({
+                data: parsedData,
+                status: res.statusCode,
+                headers: res.headers
+              })
+            } else {
+              reject(new BlaaizError(
+                parsedData.message || 'API request failed',
+                res.statusCode,
+                parsedData.code
+              ))
+            }
+          } catch (error) {
+            reject(new BlaaizError(
+              'Failed to parse API response',
+              res.statusCode,
+              'PARSE_ERROR'
+            ))
+          }
+        })
+      })
+
+      req.on('error', (error) => {
+        reject(new BlaaizError(
+          `Request failed: ${error.message}`,
+          null,
+          'REQUEST_ERROR'
+        ))
+      })
+
+      req.on('timeout', () => {
+        req.destroy()
+        reject(new BlaaizError(
+          'Request timeout',
+          null,
+          'TIMEOUT_ERROR'
+        ))
+      })
+
+      if (data && method.toUpperCase() !== 'GET') {
+        req.write(JSON.stringify(data))
+      }
+
+      req.end()
+    })
+  }
+}
+
+module.exports = BlaaizAPIClient

package/src/error.js

@@ -0,0 +1,10 @@
+class BlaaizError extends Error {
+  constructor(message, status, code) {
+    super(message)
+    this.name = 'BlaaizError'
+    this.status = status
+    this.code = code
+  }
+}
+
+module.exports = BlaaizError

package/src/index.js

@@ -0,0 +1,132 @@
+const BlaaizError = require('./error')
+const BlaaizAPIClient = require('./client')
+
+const CustomerService = require('./services/CustomerService')
+const CollectionService = require('./services/CollectionService')
+const PayoutService = require('./services/PayoutService')
+const WalletService = require('./services/WalletService')
+const VirtualBankAccountService = require('./services/VirtualBankAccountService')
+const TransactionService = require('./services/TransactionService')
+const BankService = require('./services/BankService')
+const CurrencyService = require('./services/CurrencyService')
+const FeesService = require('./services/FeesService')
+const FileService = require('./services/FileService')
+const WebhookService = require('./services/WebhookService')
+
+class Blaaiz {
+  constructor (apiKey, options = {}) {
+    this.client = new BlaaizAPIClient(apiKey, options)
+
+    this.customers = new CustomerService(this.client)
+    this.collections = new CollectionService(this.client)
+    this.payouts = new PayoutService(this.client)
+    this.wallets = new WalletService(this.client)
+    this.virtualBankAccounts = new VirtualBankAccountService(this.client)
+    this.transactions = new TransactionService(this.client)
+    this.banks = new BankService(this.client)
+    this.currencies = new CurrencyService(this.client)
+    this.fees = new FeesService(this.client)
+    this.files = new FileService(this.client)
+    this.webhooks = new WebhookService(this.client)
+  }
+
+  async testConnection () {
+    try {
+      await this.currencies.list()
+      return true
+    } catch (error) {
+      return false
+    }
+  }
+
+  async createCompleteePayout (payoutConfig) {
+    const { customerData, payoutData } = payoutConfig
+
+    try {
+      let customerId = payoutData.customer_id
+      if (!customerId && customerData) {
+        const customerResult = await this.customers.create(customerData)
+        customerId = customerResult.data.data.id
+      }
+
+      const feeBreakdown = await this.fees.getBreakdown({
+        from_currency_id: payoutData.from_currency_id,
+        to_currency_id: payoutData.to_currency_id,
+        from_amount: payoutData.from_amount
+      })
+
+      const payoutResult = await this.payouts.initiate({
+        ...payoutData,
+        customer_id: customerId
+      })
+
+      return {
+        customer_id: customerId,
+        payout: payoutResult.data,
+        fees: feeBreakdown.data
+      }
+    } catch (error) {
+      throw new BlaaizError(
+        `Complete payout failed: ${error.message}`,
+        error.status,
+        error.code
+      )
+    }
+  }
+
+  async createCompleteCollection (collectionConfig) {
+    const { customerData, collectionData, createVBA = false } = collectionConfig
+
+    try {
+      let customerId = collectionData.customer_id
+      if (!customerId && customerData) {
+        const customerResult = await this.customers.create(customerData)
+        customerId = customerResult.data.data.id
+      }
+
+      let vbaData = null
+      if (createVBA) {
+        const vbaResult = await this.virtualBankAccounts.create({
+          wallet_id: collectionData.wallet_id,
+          account_name: customerData ? `${customerData.first_name} ${customerData.last_name}` : 'Customer Account'
+        })
+        vbaData = vbaResult.data
+      }
+
+      const collectionResult = await this.collections.initiate({
+        ...collectionData,
+        customer_id: customerId
+      })
+
+      return {
+        customer_id: customerId,
+        collection: collectionResult.data,
+        virtual_account: vbaData
+      }
+    } catch (error) {
+      throw new BlaaizError(
+        `Complete collection failed: ${error.message}`,
+        error.status,
+        error.code
+      )
+    }
+  }
+}
+
+module.exports = {
+  Blaaiz,
+  BlaaizError,
+  CustomerService,
+  CollectionService,
+  PayoutService,
+  WalletService,
+  VirtualBankAccountService,
+  TransactionService,
+  BankService,
+  CurrencyService,
+  FeesService,
+  FileService,
+  WebhookService
+}
+
+module.exports.default = Blaaiz

package/src/services/BankService.js

@@ -0,0 +1,22 @@
+class BankService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async list () {
+    return this.client.makeRequest('GET', '/api/external/bank')
+  }
+
+  async lookupAccount (lookupData) {
+    const requiredFields = ['account_number', 'bank_id']
+    for (const field of requiredFields) {
+      if (!lookupData[field]) {
+        throw new Error(`${field} is required`)
+      }
+    }
+
+    return this.client.makeRequest('POST', '/api/external/bank/account-lookup', lookupData)
+  }
+}
+
+module.exports = BankService

package/src/services/CollectionService.js

@@ -0,0 +1,37 @@
+class CollectionService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async initiate (collectionData) {
+    const requiredFields = ['method', 'amount', 'wallet_id']
+    for (const field of requiredFields) {
+      if (!collectionData[field]) {
+        throw new Error(`${field} is required`)
+      }
+    }
+
+    return this.client.makeRequest('POST', '/api/external/collection', collectionData)
+  }
+
+  async initiateCrypto (cryptoData) {
+    return this.client.makeRequest('POST', '/api/external/collection/crypto', cryptoData)
+  }
+
+  async attachCustomer (attachData) {
+    const requiredFields = ['customer_id', 'transaction_id']
+    for (const field of requiredFields) {
+      if (!attachData[field]) {
+        throw new Error(`${field} is required`)
+      }
+    }
+
+    return this.client.makeRequest('POST', '/api/external/collection/attach-customer', attachData)
+  }
+
+  async getCryptoNetworks () {
+    return this.client.makeRequest('GET', '/api/external/collection/crypto/networks')
+  }
+}
+
+module.exports = CollectionService

package/src/services/CurrencyService.js

@@ -0,0 +1,11 @@
+class CurrencyService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async list () {
+    return this.client.makeRequest('GET', '/api/external/currency')
+  }
+}
+
+module.exports = CurrencyService

package/src/services/CustomerService.js

@@ -0,0 +1,308 @@
+class CustomerService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async create (customerData) {
+    const requiredFields = ['first_name', 'last_name', 'type', 'email', 'country', 'id_type', 'id_number']
+    for (const field of requiredFields) {
+      if (!customerData[field]) {
+        throw new Error(`${field} is required`)
+      }
+    }
+
+    if (customerData.type === 'business' && !customerData.business_name) {
+      throw new Error('business_name is required when type is business')
+    }
+
+    return this.client.makeRequest('POST', '/api/external/customer', customerData)
+  }
+
+  async list () {
+    return this.client.makeRequest('GET', '/api/external/customer')
+  }
+
+  async get (customerId) {
+    if (!customerId) {
+      throw new Error('Customer ID is required')
+    }
+    return this.client.makeRequest('GET', `/api/external/customer/${customerId}`)
+  }
+
+  async update (customerId, updateData) {
+    if (!customerId) {
+      throw new Error('Customer ID is required')
+    }
+    return this.client.makeRequest('PUT', `/api/external/customer/${customerId}`, updateData)
+  }
+
+  async addKYC (customerId, kycData) {
+    if (!customerId) {
+      throw new Error('Customer ID is required')
+    }
+    return this.client.makeRequest('POST', `/api/external/customer/${customerId}/kyc-data`, kycData)
+  }
+
+  async uploadFiles (customerId, fileData) {
+    if (!customerId) {
+      throw new Error('Customer ID is required')
+    }
+    return this.client.makeRequest('PUT', `/api/external/customer/${customerId}/files`, fileData)
+  }
+
+  async uploadFileComplete (customerId, fileOptions) {
+    if (!customerId) {
+      throw new Error('Customer ID is required')
+    }
+
+    if (!fileOptions) {
+      throw new Error('File options are required')
+    }
+
+    const { file, file_category } = fileOptions // eslint-disable-line camelcase
+    let { filename, contentType } = fileOptions
+
+    if (!file) {
+      throw new Error('File is required')
+    }
+
+    if (!file_category) { // eslint-disable-line camelcase
+      throw new Error('file_category is required')
+    }
+
+    if (!['identity', 'proof_of_address', 'liveness_check'].includes(file_category)) { // eslint-disable-line camelcase
+      throw new Error('file_category must be one of: identity, proof_of_address, liveness_check')
+    }
+
+    try {
+      const presignedResponse = await this.client.makeRequest('POST', '/api/external/file/get-presigned-url', {
+        customer_id: customerId, // eslint-disable-line camelcase
+        file_category // eslint-disable-line camelcase
+      })
+
+      const { url: presignedUrl, file_id } = presignedResponse.data.data // eslint-disable-line camelcase
+
+      let fileBuffer
+      if (Buffer.isBuffer(file)) {
+        fileBuffer = file
+      } else if (typeof file === 'string') {
+        if (file.startsWith('data:')) {
+          // Handle data URL format: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABmX/9k=
+          const base64Data = file.split(',')[1]
+          fileBuffer = Buffer.from(base64Data, 'base64')
+
+          // Extract content type from data URL if not provided
+          if (!contentType) {
+            const mimeMatch = file.match(/data:([^;]+)/)
+            if (mimeMatch) {
+              contentType = mimeMatch[1]
+            }
+          }
+        } else if (file.startsWith('http://') || file.startsWith('https://')) {
+          // Handle URL - download the file
+          const downloadResult = await this._downloadFile(file)
+          fileBuffer = downloadResult.buffer
+
+          // Use detected content type if not provided
+          if (!contentType && downloadResult.contentType) {
+            contentType = downloadResult.contentType
+          }
+
+          // Use filename from URL if not provided
+          if (!filename && downloadResult.filename) {
+            filename = downloadResult.filename
+          }
+        } else {
+          // Handle plain base64 string
+          fileBuffer = Buffer.from(file, 'base64')
+        }
+      } else {
+        // Handle Uint8Array or other array-like structures
+        fileBuffer = Buffer.from(file)
+      }
+
+      await this._uploadToS3(presignedUrl, fileBuffer, contentType, filename)
+
+      const fileAssociation = await this.client.makeRequest('PUT', `/api/external/customer/${customerId}/files`, {
+        id_file: file_id // eslint-disable-line camelcase
+      })
+
+      return {
+        ...fileAssociation,
+        file_id, // eslint-disable-line camelcase
+        presigned_url: presignedUrl
+      }
+    } catch (error) {
+      throw new Error(`File upload failed: ${error.message}`)
+    }
+  }
+
+  async _uploadToS3 (presignedUrl, fileBuffer, contentType, filename) {
+    const https = require('https')
+    const { URL } = require('url')
+
+    return new Promise((resolve, reject) => {
+      const url = new URL(presignedUrl)
+
+      const headers = {
+        'Content-Length': fileBuffer.length
+      }
+
+      if (contentType) {
+        headers['Content-Type'] = contentType
+      }
+
+      if (filename) {
+        headers['Content-Disposition'] = `attachment; filename="${filename}"`
+      }
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || 443,
+        path: url.pathname + url.search,
+        method: 'PUT',
+        headers
+      }
+
+      const req = https.request(options, (res) => {
+        let responseData = ''
+
+        res.on('data', (chunk) => {
+          responseData += chunk
+        })
+
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve({
+              status: res.statusCode,
+              data: responseData
+            })
+          } else {
+            reject(new Error(`S3 upload failed with status ${res.statusCode}: ${responseData}`))
+          }
+        })
+      })
+
+      req.on('error', (error) => {
+        reject(new Error(`S3 upload request failed: ${error.message}`))
+      })
+
+      req.write(fileBuffer)
+      req.end()
+    })
+  }
+
+  async _downloadFile (url) {
+    const https = require('https')
+    const http = require('http')
+    const { URL } = require('url')
+    const path = require('path')
+
+    return new Promise((resolve, reject) => {
+      const urlObj = new URL(url)
+      const client = urlObj.protocol === 'https:' ? https : http
+
+      const options = {
+        hostname: urlObj.hostname,
+        port: urlObj.port || (urlObj.protocol === 'https:' ? 443 : 80),
+        path: urlObj.pathname + urlObj.search,
+        method: 'GET',
+        headers: {
+          'User-Agent': 'Blaaiz-NodeJS-SDK/1.0.0'
+        }
+      }
+
+      const req = client.request(options, (res) => {
+        // Handle redirects
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          return this._downloadFile(res.headers.location)
+            .then(resolve)
+            .catch(reject)
+        }
+
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          reject(new Error(`Failed to download file: HTTP ${res.statusCode}`))
+          return
+        }
+
+        const chunks = []
+        let totalLength = 0
+
+        res.on('data', (chunk) => {
+          chunks.push(chunk)
+          totalLength += chunk.length
+        })
+
+        res.on('end', () => {
+          const buffer = Buffer.concat(chunks, totalLength)
+
+          // Extract content type from response headers
+          const contentType = res.headers['content-type']
+
+          // Extract filename from URL path or Content-Disposition header
+          let filename = null
+
+          // Try Content-Disposition header first
+          const contentDisposition = res.headers['content-disposition']
+          if (contentDisposition) {
+            const filenameMatch = contentDisposition.match(/filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/)
+            if (filenameMatch) {
+              filename = filenameMatch[1].replace(/['"]/g, '')
+            }
+          }
+
+          // Fallback to URL path
+          if (!filename) {
+            const urlPath = urlObj.pathname
+            filename = path.basename(urlPath)
+
+            // If no extension, try to add one based on content type
+            if (!path.extname(filename) && contentType) {
+              const ext = this._getExtensionFromContentType(contentType)
+              if (ext) {
+                filename += ext
+              }
+            }
+          }
+
+          resolve({
+            buffer,
+            contentType,
+            filename
+          })
+        })
+      })
+
+      req.on('error', (error) => {
+        reject(new Error(`File download failed: ${error.message}`))
+      })
+
+      req.setTimeout(30000, () => {
+        req.destroy()
+        reject(new Error('File download timeout'))
+      })
+
+      req.end()
+    })
+  }
+
+  _getExtensionFromContentType (contentType) {
+    const mimeToExt = {
+      'image/jpeg': '.jpg',
+      'image/jpg': '.jpg',
+      'image/png': '.png',
+      'image/gif': '.gif',
+      'image/webp': '.webp',
+      'image/bmp': '.bmp',
+      'image/tiff': '.tiff',
+      'application/pdf': '.pdf',
+      'text/plain': '.txt',
+      'application/msword': '.doc',
+      'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx'
+    }
+
+    return mimeToExt[contentType.split(';')[0]] || null
+  }
+}
+
+module.exports = CustomerService

package/src/services/FeesService.js

@@ -0,0 +1,18 @@
+class FeesService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async getBreakdown (feeData) {
+    const requiredFields = ['from_currency_id', 'to_currency_id', 'from_amount']
+    for (const field of requiredFields) {
+      if (!feeData[field]) {
+        throw new Error(`${field} is required`)
+      }
+    }
+
+    return this.client.makeRequest('POST', '/api/external/fees/breakdown', feeData)
+  }
+}
+
+module.exports = FeesService

package/src/services/FileService.js

@@ -0,0 +1,18 @@
+class FileService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async getPresignedUrl (fileData) {
+    const requiredFields = ['customer_id', 'file_category']
+    for (const field of requiredFields) {
+      if (!fileData[field]) {
+        throw new Error(`${field} is required`)
+      }
+    }
+
+    return this.client.makeRequest('POST', '/api/external/file/get-presigned-url', fileData)
+  }
+}
+
+module.exports = FileService

package/src/services/PayoutService.js

@@ -0,0 +1,31 @@
+class PayoutService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async initiate (payoutData) {
+    const requiredFields = ['wallet_id', 'method', 'from_amount', 'from_currency_id', 'to_currency_id']
+    for (const field of requiredFields) {
+      if (!payoutData[field]) {
+        throw new Error(`${field} is required`)
+      }
+    }
+
+    if (payoutData.method === 'bank_transfer' && !payoutData.account_number) {
+      throw new Error('account_number is required for bank_transfer method')
+    }
+
+    if (payoutData.method === 'interac') {
+      const interacFields = ['email', 'interac_first_name', 'interac_last_name']
+      for (const field of interacFields) {
+        if (!payoutData[field]) {
+          throw new Error(`${field} is required for interac method`)
+        }
+      }
+    }
+
+    return this.client.makeRequest('POST', '/api/external/payout', payoutData)
+  }
+}
+
+module.exports = PayoutService

package/src/services/TransactionService.js

@@ -0,0 +1,18 @@
+class TransactionService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async list (filters = {}) {
+    return this.client.makeRequest('POST', '/api/external/transaction', filters)
+  }
+
+  async get (transactionId) {
+    if (!transactionId) {
+      throw new Error('Transaction ID is required')
+    }
+    return this.client.makeRequest('GET', `/api/external/transaction/${transactionId}`)
+  }
+}
+
+module.exports = TransactionService

package/src/services/VirtualBankAccountService.js

@@ -0,0 +1,30 @@
+class VirtualBankAccountService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async create (vbaData) {
+    const requiredFields = ['wallet_id']
+    for (const field of requiredFields) {
+      if (!vbaData[field]) {
+        throw new Error(`${field} is required`)
+      }
+    }
+
+    return this.client.makeRequest('POST', '/api/external/virtual-bank-account', vbaData)
+  }
+
+  async list (walletId) {
+    const params = walletId ? `?wallet_id=${walletId}` : ''
+    return this.client.makeRequest('GET', `/api/external/virtual-bank-account${params}`)
+  }
+
+  async get (vbaId) {
+    if (!vbaId) {
+      throw new Error('Virtual bank account ID is required')
+    }
+    return this.client.makeRequest('GET', `/api/external/virtual-bank-account/${vbaId}`)
+  }
+}
+
+module.exports = VirtualBankAccountService

package/src/services/WalletService.js

@@ -0,0 +1,18 @@
+class WalletService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async list () {
+    return this.client.makeRequest('GET', '/api/external/wallet')
+  }
+
+  async get (walletId) {
+    if (!walletId) {
+      throw new Error('Wallet ID is required')
+    }
+    return this.client.makeRequest('GET', `/api/external/wallet/${walletId}`)
+  }
+}
+
+module.exports = WalletService

package/src/services/WebhookService.js

@@ -0,0 +1,96 @@
+class WebhookService {
+  constructor (client) {
+    this.client = client
+  }
+
+  async register (webhookData) {
+    const requiredFields = ['collection_url', 'payout_url']
+    for (const field of requiredFields) {
+      if (!webhookData[field]) {
+        throw new Error(`${field} is required`)
+      }
+    }
+
+    return this.client.makeRequest('POST', '/api/external/webhook', webhookData)
+  }
+
+  async get () {
+    return this.client.makeRequest('GET', '/api/external/webhook')
+  }
+
+  async update (webhookData) {
+    return this.client.makeRequest('PUT', '/api/external/webhook', webhookData)
+  }
+
+  async replay (replayData) {
+    const requiredFields = ['transaction_id']
+    for (const field of requiredFields) {
+      if (!replayData[field]) {
+        throw new Error(`${field} is required`)
+      }
+    }
+
+    return this.client.makeRequest('POST', '/api/external/webhook/replay', replayData)
+  }
+
+  verifySignature (payload, signature, secret) {
+    if (!payload) {
+      throw new Error('Payload is required for signature verification')
+    }
+
+    if (!signature) {
+      throw new Error('Signature is required for signature verification')
+    }
+
+    if (!secret) {
+      throw new Error('Webhook secret is required for signature verification')
+    }
+
+    const crypto = require('crypto')
+
+    // Convert payload to string if it's an object
+    const payloadString = typeof payload === 'string' ? payload : JSON.stringify(payload)
+
+    // Remove 'sha256=' prefix if present
+    const cleanSignature = signature.replace(/^sha256=/, '')
+
+    // Create HMAC signature
+    const expectedSignature = crypto
+      .createHmac('sha256', secret)
+      .update(payloadString, 'utf8')
+      .digest('hex')
+
+    // Use timingSafeEqual to prevent timing attacks
+    try {
+      const signatureBuffer = Buffer.from(cleanSignature, 'hex')
+      const expectedBuffer = Buffer.from(expectedSignature, 'hex')
+
+      if (signatureBuffer.length !== expectedBuffer.length) {
+        return false
+      }
+
+      return crypto.timingSafeEqual(signatureBuffer, expectedBuffer)
+    } catch (error) {
+      return false
+    }
+  }
+
+  constructEvent (payload, signature, secret) {
+    if (!this.verifySignature(payload, signature, secret)) {
+      throw new Error('Invalid webhook signature')
+    }
+
+    try {
+      const event = typeof payload === 'string' ? JSON.parse(payload) : payload
+      return {
+        ...event,
+        verified: true,
+        timestamp: new Date().toISOString()
+      }
+    } catch (error) {
+      throw new Error('Invalid webhook payload: unable to parse JSON')
+    }
+  }
+}
+
+module.exports = WebhookService