Skip to Content
SDKsNexus SDK (Cloud Integration)Node.js

Node.js SDK

GitHub Repository: sunbay-nexus-sdk-nodejs 

Official SUNBAY Nexus Node.js SDK, providing complete payment integration capabilities for Node.js applications.

Features

  • ✅ Support for TypeScript and JavaScript
  • ✅ Complete type definitions
  • ✅ Automatic authentication
  • ✅ Automatic retry for GET requests
  • ✅ Comprehensive exception handling
  • ✅ Connection pool management
  • ✅ Support for custom logging

Installation

npm install @sunbay/sunbay-nexus-sdk

Note: This SDK is written in TypeScript but compiled to JavaScript. You can use it directly in both JavaScript and TypeScript projects without any compilation steps.

Quick Start

1. Initialize Client

NexusClient is thread-safe and can be reused across multiple requests. Create once, use globally:

const { NexusClient } = require('@sunbay/sunbay-nexus-sdk');
 
const client = new NexusClient({
  apiKey: '{YOUR_API_KEY}',
  baseUrl: 'https://open.sunbay.us',
});

2. Create Payment Transaction

Important: All amount fields use the smallest currency unit (integers). For example: 100.00 USD = 10000 cents

const {
  NexusClient,
  SUNBAYBusinessError,
  SUNBAYNetworkError,
} = require('@sunbay/sunbay-nexus-sdk');
 
// Assume client is already initialized
// const client = ... (from step 1)
 
// Set expiration time (optional)
const expireTime = new Date();
expireTime.setMinutes(expireTime.getMinutes() + 10);
const timeExpire = expireTime.toISOString();
 
// Build amount (amounts use smallest currency unit, e.g., cents for USD)
const amount = {
  orderAmount: 10000, // 100.00 USD = 10000 cents
  priceCurrency: 'USD',
};
 
// Build payment request
const request = {
  appId: 'app_123456',
  merchantId: 'mch_789012',
  referenceOrderId: 'ORDER20231119001',
  transactionRequestId: `PAY_REQ_${Date.now()}`,
  amount: amount,
  description: 'Product purchase',
  terminalSn: 'T1234567890',
  timeExpire: timeExpire,
};
 
// Execute transaction
try {
  const response = await client.sale(request);
  // If code reaches here, transaction is successful (code = '0')
  console.log('Transaction ID:', response.transactionId);
  console.log('Reference Order ID:', response.referenceOrderId);
} catch (error) {
  if (error.name === 'SUNBAYNetworkError') {
    console.error('Network Error:', error.message);
    if (error.retryable) {
      console.log('This error is retryable');
    }
  } else if (error.name === 'SUNBAYBusinessError') {
    console.error('API Error:', error.code, error.message);
    if (error.traceId) {
      console.error('Trace ID:', error.traceId);
    }
  }
}

3. Query Transaction

const request = {
  appId: 'app_123456',
  merchantId: 'mch_789012',
  transactionId: 'TXN20231119001',
};
 
try {
  const response = await client.query(request);
  console.log('Transaction Status:', response.transactionStatus);
} catch (error) {
  console.error('Error:', error);
}

API Methods

The SDK provides the following API methods:

Transaction APIs

  • sale(request) - Payment transaction
  • auth(request) - Pre-authorization
  • forcedAuth(request) - Forced authorization
  • incrementalAuth(request) - Incremental authorization
  • postAuth(request) - Post-authorization completion
  • refund(request) - Refund
  • voidTransaction(request) - Void transaction
  • abort(request) - Abort transaction
  • tipAdjust(request) - Tip adjustment

Query APIs

  • query(request) - Query transaction

Settlement APIs

  • batchClose(request) - Batch settlement

Exception Handling

The SDK throws two types of errors:

  • SUNBAYNetworkError: Network-related errors (connection timeout, network errors, etc.)
  • SUNBAYBusinessError: Business logic errors (parameter validation, API business errors, etc.)

Check error type via the error.name property:

try {
  const response = await client.sale(request);
  // Handle successful response
} catch (error) {
  if (error.name === 'SUNBAYNetworkError') {
    console.error('Network Error:', error.message);
    if (error.retryable) {
      // Can retry
    }
  } else if (error.name === 'SUNBAYBusinessError') {
    console.error('API Error:', error.code, error.message);
    if (error.traceId) {
      console.error('Trace ID:', error.traceId);
    }
  }
}

Enum Types

The SDK provides enum types for improved type safety. Response fields are automatically converted from API codes/strings to enum types.

TransactionStatus

The transactionStatus field in query responses is automatically converted from API codes (I, P, S, F, C) to the TransactionStatus enum:

import { TransactionStatus } from '@sunbay/sunbay-nexus-sdk';
 
const response = await client.query(request);
 
// Use enum comparison
if (response.transactionStatus === TransactionStatus.SUCCESS) {
  console.log('Transaction successful');
}
 
// Get raw code
console.log(response.transactionStatus.getCode()); // 'S'

Available TransactionStatus values:

  • TransactionStatus.INITIAL - Initial state (code: I)
  • TransactionStatus.PROCESSING - Processing (code: P)
  • TransactionStatus.SUCCESS - Success (code: S)
  • TransactionStatus.FAIL - Failed (code: F)
  • TransactionStatus.CLOSED - Closed (code: C)

Other Enums

Other enum fields in responses are also automatically converted:

  • transactionType: TransactionType enum (SALE, AUTH, FORCED_AUTH, etc.)
  • entryMode: EntryMode enum (MANUAL, SWIPE, CONTACT, etc.)
  • cardNetworkType: CardNetworkType enum (CREDIT, DEBIT, EBT, etc.)
  • authenticationMethod: AuthenticationMethod enum (NOT_AUTHENTICATED, PIN, etc.)

Configuration Options

const client = new NexusClient({
  apiKey: 'sk_test_xxx',
  baseUrl: 'https://open.sunbay.us',  // Default: https://open.sunbay.us
  timeout: 30000,                      // Default: 30000ms (30 seconds)
  maxRetries: 3,                       // Default: 3 times (GET request retry)
  maxSockets: 200,                     // Default: 200 (max connections in pool)
  maxFreeSockets: 20,                  // Default: 20 (idle connections)
});

Connection Pool Configuration

The SDK uses axios and HTTP Agent’s connection pool to efficiently manage HTTP connections. You can configure:

  • maxSockets: Maximum connections in the pool (default: 200)
  • maxFreeSockets: Maximum idle connections to keep (default: 20)

These settings help optimize performance in high-concurrency scenarios.

Logging

The SDK supports custom loggers. By default, it uses console logging.

Using default console logging (no additional configuration needed):

const client = new NexusClient({
  apiKey: 'sk_test_xxx',
  // Uses console logging by default
});

Using winston logging:

const winston = require('winston');
 
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.Console(),
  ],
});
 
const client = new NexusClient({
  apiKey: 'sk_test_xxx',
  logger: logger,
});

System Requirements

  • Node.js 14.x or higher

Important: The SDK is compiled to JavaScript. You don’t need TypeScript to use this SDK. If you’re using JavaScript, just install and use it directly. If you’re using TypeScript in your project, you’ll automatically get full type definitions and IntelliSense support.

License

MIT License

Last updated on
JavaGo