Paynamics Node.js TypeScript SDK

A TypeScript SDK for integrating with Paynamics payment gateway (UNOFFICIAL)

⚠️ This package is currently under development and not yet published to npm. Features and APIs may change.

📁 Project Structure

paynamics-pay/
├── src/
│   ├── config/          # API configuration classes
│   ├── core/            # Main client classes  
│   ├── constants/       # Enums and constants
│   ├── types/           # TypeScript interfaces
│   ├── utils/           # Utility functions
│   └── index.ts         # Main entry point
├── examples/            # Usage examples
├── tests/              # Test files
└── dist/               # Compiled output

Installation

# This package is not yet published to npm
# For development, clone the repository and build locally
git clone <repository-url>
cd paynamics-pay
npm install
npm run build

Quick Start

import { Client, RequestBody, ItemGroup } from 'paynamics-pay';

const client = new Client({
  merchantId: 'your_merchant_id',
  merchantKey: 'your_merchant_key',
  sandbox: true
});

Transaction API Usage

import { Client, RequestBody, ItemGroup } from 'paynamics-pay';

// Initialize client
const client = new Client({
  merchantId: 'your_merchant_id',
  merchantKey: 'your_merchant_key',
  sandbox: true
});

// Create transaction request
const requestBody = new RequestBody({
  request_id: RequestBody.generateRequestId(),
  notification_url: 'https://yoursite.com/notify',
  response_url: 'https://yoursite.com/response',
  cancel_url: 'https://yoursite.com/cancel',
  currency: 'PHP',
  pay_reference: 'ORDER_' + Date.now(),
  expiry_limit: RequestBody.formatExpiryLimit(new Date(Date.now() + 24 * 60 * 60 * 1000))
});

// Set customer info
requestBody.setCustomerInfo({
  fname: 'John',
  lname: 'Doe',
  email: '[email protected]'
});

// Set billing info
requestBody.setBillingInfo({
  billing_address1: 'Your Address Here'
});

// Add items
const items = new ItemGroup();
items.addItem({
  name: 'Product Name',
  quantity: 1,
  amount: 100.00
});

requestBody.setItemGroup(items);

// Execute payment
try {
  const response = await client.createOTCPayment(requestBody);
  console.log('Payment URL:', response.paymentUrl);
  console.log('Request ID:', response.requestId);
} catch (error) {
  console.error('Payment error:', error);
}

Examples

Check the examples/ directory for complete usage examples:

# Run transaction API example
npm run example:transaction

# Run basic client example  
npm run example

Client Initialization

Basic Usage

import { Client, PaynamicsConfig } from 'paynamics-pay';

// Initialize with configuration object
const config: PaynamicsConfig = {
  merchantId: 'your_merchant_id',
  merchantKey: 'your_merchant_key',
  sandbox: true // Use false for production
};

const client = new Client(config);

Alternative Initialization Methods

// Initialize empty client and set config later
const client = new Client();
client.setConfig({
  merchantId: 'your_merchant_id',
  merchantKey: 'your_merchant_key',
  sandbox: true
});

// Method chaining
const client = new Client()
  .setMerchantId('your_merchant_id')
  .setMerchantKey('your_merchant_key')
  .setSandbox(true);

Features

• ✅ Client Configuration - Merchant ID, key, sandbox/production mode
• ✅ Transaction API - Complete payment processing support
• ✅ Request Body Builder - Easy transaction request building (similar to PHP SDK)
• ✅ Item Management - Add/remove items with automatic calculations
• ✅ Multiple Payment Methods - OTC, Credit Card, Bank Transfer
• ✅ Signature Generation - Automatic security signature handling
• ✅ HTTP Client - Built-in API communication with error handling
• ✅ TypeScript Support - Full type definitions and IntelliSense
• ✅ Environment Support - Sandbox and production configurations

Payment Methods Supported

• OTC (Over The Counter) - MLhuillier, ECPay, etc.
• Credit Card - Visa, Mastercard, etc.
• Bank Transfer - Online banking
• Wallet - GCash, WeChat, AliPay, etc

API Reference

See detailed documentation:

• 📖 Transaction API Guide - Complete transaction API usage

Development

# Install dependencies
npm install

# Build the library
npm run build

# Watch mode for development
npm run dev

Environment Configuration

For production environment, make sure to set:

const client = new Client({
  merchantId: 'your_production_merchant_id',
  merchantKey: 'your_production_merchant_key',
  sandbox: false,
  productionUrl: 'https://your-production-url.com/webpaymentV2/default.aspx'
});

Configuration Validation

The client provides a validation method to ensure all required configuration is set:

try {
  client.validateConfig();
  console.log('Configuration is valid');
} catch (error) {
  console.error('Configuration error:', error.message);
}

Getting Configuration Values

// Get individual values
const merchantId = client.getMerchantId();
const merchantKey = client.getMerchantKey();
const isSandbox = client.isSandbox();
const requestUrl = client.getRequestUrl();

// Get full configuration
const config = client.getConfig();

Constants

The SDK provides TypeScript enums for transaction types and security options:

import { TransactionType, Secure3d } from 'paynamics-pay';

// Transaction Types
console.log(TransactionType.SALE);          // 'sale'
console.log(TransactionType.AUTHORIZED);    // 'authorized'
console.log(TransactionType.PREAUTHORIZED); // 'preauthorized'

// Secure3D Options
console.log(Secure3d.TRY3D);   // 'try3d'
console.log(Secure3d.ENABLED); // 'enabled'

Error Handling

The SDK throws typed errors for configuration issues:

try {
  client.setMerchantId(123); // This will throw an error
} catch (error) {
  console.error(error.message); // "Merchant ID should be string"
}

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import { Client, PaynamicsConfig, ClientInterface } from 'paynamics-pay';

// All types are exported and available for use
const config: PaynamicsConfig = {
  merchantId: 'test',
  merchantKey: 'test',
  sandbox: true
};

Development Status

This SDK is currently under active development. Current status:

• ✅ Client initialization and configuration
• ✅ Request body building
• ✅ Item management
• ✅ Basic transaction API
• ✅ TypeScript support
• 🚧 HTTP client implementation (in progress)
• 🚧 Response handling (in progress)
• 🚧 Error management (in progress)
• ⏳ Payment method validation
• ⏳ Webhook handling
• ⏳ npm package publication

Contributing

This project is open for contributions. Please check the issues and submit pull requests.