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 error handling
  • ✅ HTTP connection pool (axios + HTTP Agent)
  • ✅ 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 uses an internal HTTP connection pool. Create it once and reuse it globally — do not create a new instance for every request. Repeated creation wastes connection pool resources.

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

We recommend tuning connectTimeout, readTimeout, maxRetries, maxTotal, and maxPerRoute based on your concurrency level and business requirements. See Configuration Options for details.

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 (from step 1)
 
const request = {
  appId: 'app_123456',
  merchantId: 'mch_789012',
  referenceOrderId: 'ORDER20231119001',
  transactionRequestId: `PAY_REQ_${Date.now()}`,
  amount: {
    orderAmount: 10000, // 100.00 USD = 10000 cents
    priceCurrency: 'USD',
  },
  description: 'Product purchase',
  terminalSn: 'T1234567890',
};
 
try {
  const response = await client.sale(request);
  console.log('Transaction ID:', response.transactionId);
} 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);
    }
  }
}

API Methods

All request types are TypeScript interfaces. Requests are constructed as plain object literals.

In-Person Payment 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
  • batchQuery(request) - Query open (unsettled) batches
  • batchClose(request) - Batch settlement
  • batchCloseList(request) - Query closed (settled) batches

Online Payment APIs

  • createCheckoutSession(request) - Create hosted checkout session
  • expireCheckoutSession(request) - Expire a checkout session
  • checkoutDirectPayment(request) - Direct payment (server-to-server)
  • onlineRefund(request) - Online refund

Transaction Query APIs

  • query(request) - Query transaction

Merchant APIs

  • merchantQuery(request) - Retrieve merchant information
  • merchantTerminalsQuery(request) - List terminals bound to a merchant

Error 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.)
try {
  const response = await client.sale(request);
} 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 to enum types.

TransactionStatus

import { TransactionStatus } from '@sunbay/sunbay-nexus-sdk';
 
const response = await client.query(request);
 
if (response.transactionStatus === TransactionStatus.SUCCESS) {
  console.log('Transaction successful');
}
 
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

  • TransactionType - SALE, AUTH, FORCED_AUTH, INCREMENTAL, POST_AUTH, REFUND, VOID
  • EntryMode - MANUAL, SWIPE, FALLBACK_SWIPE, CONTACT, CONTACTLESS
  • CardNetworkType - CREDIT, DEBIT, EBT, EGC, UNKNOWN
  • PaymentCategory - CARD, CARD_CREDIT, CARD_DEBIT, QR_MPM, QR_CPM
  • AuthenticationMethod - NOT_AUTHENTICATED, PIN, OFFLINE_PIN, BY_PASS, SIGNATURE
  • RelatedTransactionStatus - VOIDED, INCREMENTAL, REFUNDED, CAPTURE, PART_REFUNDED
  • TransactionBatchStatus - N, U, C

Configuration Options

const client = new NexusClient({
  apiKey: 'sk_test_xxx',                    // Required: API key
  baseUrl: 'https://open.sunbay.us',        // Default: https://open.sunbay.us
  connectTimeout: 10000,                     // Default: 10000ms (10 seconds)
  readTimeout: 30000,                        // Default: 30000ms (30 seconds)
  maxRetries: 3,                             // Default: 3 times (GET request retry)
  maxTotal: 200,                             // Default: 200 (max connections in pool)
  maxPerRoute: 200,                          // Default: 200 (max connections per route)
});

Logging

The SDK supports custom loggers compatible with debug(), info(), warn(), error() methods (e.g., winston, pino). By default it uses console logging with [sunbay-nexus-sdk] prefix.

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 18.x or higher
  • axios 1.6+

The SDK is compiled to JavaScript. You don’t need TypeScript to use this SDK. TypeScript projects will automatically get full type definitions and IntelliSense support.

License

MIT License

Last updated on
JavaGo