BixyPay Fintech SDK - Node.js/TypeScript

Official Node.js/TypeScript SDK for the BixyPay Fintech API Platform.

Installation

npm install @bixypay/fintech-sdk
# or
yarn add @bixypay/fintech-sdk
# or
pnpm add @bixypay/fintech-sdk

Quick Start

1. Initialize the Client

import { BixyPayClient } from '@bixypay/fintech-sdk';

const client = new BixyPayClient({
  baseUrl: 'https://your-api-url.com',
  apiKey: 'your-api-key-here', // Optional: for API key authentication
  jwtToken: 'your-jwt-token',  // Optional: for JWT authentication
});

2. Authentication

Register a New Merchant

const { data, error } = await client.auth.register({
  email: '[email protected]',
  password: 'SecurePassword123!',
  businessName: 'Acme Corporation',
  businessAddress: '123 Business St, City, Country'
});

if (error) {
  console.error('Registration failed:', error);
} else {
  console.log('Merchant registered:', data);
}

Login and Get JWT Token

const { data, error } = await client.auth.login({
  email: '[email protected]',
  password: 'SecurePassword123!'
});

if (error) {
  console.error('Login failed:', error);
} else {
  console.log('Login successful:', data);
  // JWT token is automatically stored in the client
}

Create API Key

const { data, error } = await client.auth.createApiKey({
  name: 'Production API Key',
  scopes: ['read', 'write']
});

if (error) {
  console.error('Failed to create API key:', error);
} else {
  console.log('API Key created:', data);
  // Use the returned API key for future requests
  client.setApiKey(data.key);
}

List All API Keys

const { data, error } = await client.auth.listApiKeys();

if (error) {
  console.error('Failed to list API keys:', error);
} else {
  console.log('API Keys:', data);
}

Revoke an API Key

const { data, error } = await client.auth.revokeApiKey('key-id-here');

if (error) {
  console.error('Failed to revoke API key:', error);
} else {
  console.log('API key revoked successfully');
}

3. Merchant Operations

Get Merchant Profile

const { data, error } = await client.merchants.getProfile();

if (error) {
  console.error('Failed to get profile:', error);
} else {
  console.log('Merchant profile:', data);
}

Get Account Balance

const { data, error } = await client.merchants.getBalance();

if (error) {
  console.error('Failed to get balance:', error);
} else {
  console.log('Balance:', data);
}

Update KYC Status

const { data, error } = await client.merchants.updateKycStatus('approved');

if (error) {
  console.error('Failed to update KYC status:', error);
} else {
  console.log('KYC status updated:', data);
}

4. Invoice Management

Create an Invoice

const { data, error } = await client.invoices.create({
  amount: 100.50,
  currency: 'USD',
  description: 'Payment for Product XYZ',
  metadata: {
    orderId: '12345',
    customerId: 'cust_abc'
  },
  callbackUrl: 'https://yourapp.com/webhook'
});

if (error) {
  console.error('Failed to create invoice:', error);
} else {
  console.log('Invoice created:', data);
}

Get Invoice by ID

const { data, error } = await client.invoices.get('invoice-id-here');

if (error) {
  console.error('Failed to get invoice:', error);
} else {
  console.log('Invoice details:', data);
}

List All Invoices (with Pagination)

const { data, error } = await client.invoices.list({
  page: 1,
  limit: 20
});

if (error) {
  console.error('Failed to list invoices:', error);
} else {
  console.log('Invoices:', data);
}

Update Invoice Status

const { data, error} = await client.invoices.updateStatus(
  'invoice-id-here',
  'completed',  // Status: 'pending', 'completed', 'failed'
  '0x1234567890abcdef'  // Optional: transaction hash for completed payments
);

if (error) {
  console.error('Failed to update invoice:', error);
} else {
  console.log('Invoice updated:', data);
}

5. Webhook Management

Create a Webhook

const { data, error } = await client.webhooks.create({
  url: 'https://yourapp.com/webhooks/payment',
  events: ['payment.completed', 'payment.failed', 'payout.processed']
});

if (error) {
  console.error('Failed to create webhook:', error);
} else {
  console.log('Webhook created:', data);
  console.log('Webhook secret:', data.secret); // Save this for verification
}

List All Webhooks

const { data, error } = await client.webhooks.list();

if (error) {
  console.error('Failed to list webhooks:', error);
} else {
  console.log('Webhooks:', data);
}

Delete a Webhook

const { data, error } = await client.webhooks.delete('webhook-id-here');

if (error) {
  console.error('Failed to delete webhook:', error);
} else {
  console.log('Webhook deleted successfully');
}

Complete Example: Payment Flow

import { BixyPayClient } from '@bixypay/fintech-sdk';

async function processPayment() {
  // Initialize client
  const client = new BixyPayClient({
    baseUrl: 'https://your-api-url.com',
    apiKey: 'your-api-key'
  });

  try {
    // Create invoice
    const invoice = await client.invoices.create({
      amount: 250.00,
      currency: 'USD',
      description: 'Premium Subscription - Monthly',
      metadata: {
        planType: 'premium',
        billingCycle: 'monthly',
        userId: 'user_12345'
      },
      callbackUrl: 'https://yourapp.com/webhooks/payment'
    });

    if (invoice.error) {
      throw new Error(`Invoice creation failed: ${invoice.error}`);
    }

    console.log('✓ Invoice created:', invoice.data);

    // Get invoice status
    const status = await client.invoices.get(invoice.data.id);
    
    if (status.error) {
      throw new Error(`Failed to get invoice status: ${status.error}`);
    }

    console.log('✓ Invoice status:', status.data);

    return invoice.data;

  } catch (error) {
    console.error('Payment processing error:', error);
    throw error;
  }
}

processPayment();

Error Handling

All SDK methods return a response object with data and error properties:

const { data, error } = await client.invoices.create({...});

if (error) {
  // Handle error
  console.error('Error:', error.message);
  console.error('Status:', error.status);
} else {
  // Success - use data
  console.log('Success:', data);
}

TypeScript Support

The SDK is fully typed with TypeScript. All request/response types are auto-generated from the OpenAPI specification:

import type { paths } from '@bixypay/fintech-sdk/types';

// All endpoints are typed
const invoice: paths['/api/v1/transactions/invoices']['post']['responses']['201'] = ...;

Authentication Methods

API Key Authentication (Recommended for Server-to-Server)

const client = new BixyPayClient({
  baseUrl: 'https://your-api-url.com',
  apiKey: 'sk_live_your-api-key'
});

JWT Authentication (For Dashboard/Admin Access)

const client = new BixyPayClient({
  baseUrl: 'https://your-api-url.com'
});

// Login to get JWT token
await client.auth.login({
  email: '[email protected]',
  password: 'password'
});

// JWT token is automatically stored and used for subsequent requests

Switching Between Auth Methods

const client = new BixyPayClient({
  baseUrl: 'https://your-api-url.com'
});

// Use JWT for admin operations
client.setJwtToken('your-jwt-token');
await client.merchants.getProfile();

// Switch to API key for programmatic access
client.setApiKey('your-api-key');
await client.invoices.create({...});

Rate Limiting

The API enforces rate limiting:

• 100 requests per minute per API key

The SDK automatically includes rate limit information in responses.

Support

• Documentation: https://docs.bixypay.com
• API Reference: https://your-api-url.com/api/docs
• Issues: https://github.com/bixypay/fintech-sdk/issues

License

MIT License - See LICENSE file for details