payway-ts

payway-ts

TypeScript SDK for ABA PayWay payment integration - Supports both client-side form submission and server-to-server API calls

An unofficial, type-safe TypeScript SDK for ABA PayWay payment integration. This SDK provides two integration patterns:

• Payload Builder - Build signed payloads for client-side form submission (recommended for abapay)
• Server-to-Server - Execute API calls directly from your server (for other payment options)

[!WARNING]
This is not a product of ABA Bank. This is an unofficial implementation based on https://www.payway.com.kh/developers/

Credits

This package is built upon and inspired by the excellent work of Seanghay Yath and the original payway-js package. We've extended it with:

• Full TypeScript support with comprehensive type definitions
• Pre-Authorization transactions (complete, cancel, with payout)
• RSA encryption for sensitive operations
• Dual integration patterns (payload builder + execute)
• Enhanced error handling with detailed API responses
• Extensive documentation and examples

Special thanks to the original contributors for laying the foundation!

Features

Core Features (from original payway-js)

• Create transactions
• Check transaction status
• List transactions
• HMAC-SHA512 request signing

New Features in payway-ts

• Full TypeScript Support - Complete type definitions with autocomplete
• Pre-Authorization Transactions - Complete, cancel, and payout support with RSA encryption
• Dual Integration Modes - Client-side form submission OR server-to-server API calls
• Enhanced Error Handling - Detailed API error responses with status codes and bodies
• RSA Encryption - Secure data encryption for sensitive operations (117-byte chunking)
• Server-Side Security - Build payloads securely on your server (Node.js 18+)
• ES Modules - Native ESM support
• Minimal Dependencies - Only date-fns for date formatting
• Next.js Ready - Works seamlessly with Next.js API routes
• Smart Validation - Prevents common mistakes (e.g., using abapay with server-to-server)

Installation

npm install payway-ts

Requirements

• Node.js 18.0.0 or higher
• ABA Bank merchant account with API credentials

Quick Start

Pattern 1: Client-Side Form Submission (for abapay)

Use this when the browser needs to submit directly to ABA PayWay.

// Server: Build signed payload
import { PayWayClient } from 'payway-ts';

const client = new PayWayClient(
  process.env.PAYWAY_BASE_URL!,
  process.env.PAYWAY_MERCHANT_ID!,
  process.env.PAYWAY_API_KEY!
);

const payload = client.buildTransactionPayload({
  amount: 100,
  tran_id: 'ORDER-123',
  payment_option: 'abapay',
  return_url: 'https://yoursite.com/callback'
});

// Send payload to client
return Response.json(payload);

// Client: Create and submit form
const form = document.createElement('form');
form.method = payload.method;
form.action = payload.url;

for (const [key, value] of Object.entries(payload.fields)) {
  const input = document.createElement('input');
  input.type = 'hidden';
  input.name = key;
  input.value = String(value);
  form.appendChild(input);
}

document.body.appendChild(form);
form.submit();

See detailed guide →

Pattern 2: Server-to-Server (for other payment options)

Use this when your server communicates directly with the ABA API.

import { PayWayClient } from 'payway-ts';

const client = new PayWayClient(
  process.env.PAYWAY_BASE_URL!,
  process.env.PAYWAY_MERCHANT_ID!,
  process.env.PAYWAY_API_KEY!
);

// Create transaction
const result = await client.execute(
  client.buildTransactionPayload({
    amount: 100,
    tran_id: 'ORDER-123',
    payment_option: 'cards',  // NOT 'abapay'
    return_url: 'https://yoursite.com/callback'
  })
);

// Check transaction status
const status = await client.execute(
  client.buildCheckTransactionPayload('ORDER-123')
);

// List transactions
const transactions = await client.execute(
  client.buildTransactionListPayload({
    from_date: '20240101000000',
    to_date: '20240131235959'
  })
);

See detailed guide →

Documentation

Comprehensive guides for every use case:

• Getting Started - Choose your integration pattern
• Client-Side Form Submission - Pattern 1 guide for abapay
• Server-to-Server - Pattern 2 guide for API calls
• Pre-Authorization - Two-step payment process
• API Reference - Complete method documentation
• Error Handling - Handle errors properly
• Security Best Practices - Keep your integration secure

Environment Variables

Create a .env.local file:

# Sandbox
PAYWAY_BASE_URL=https://checkout-sandbox.payway.com.kh/
PAYWAY_MERCHANT_ID=your_sandbox_merchant_id
PAYWAY_API_KEY=your_sandbox_api_key

# Production
# PAYWAY_BASE_URL=https://checkout.payway.com.kh/
# PAYWAY_MERCHANT_ID=your_production_merchant_id
# PAYWAY_API_KEY=your_production_api_key

# Optional: For pre-authorization
# ABA_RSA_PUBLIC_KEY=your_rsa_public_key

NEXT_PUBLIC_APP_URL=https://yoursite.com

TypeScript Support

All methods are fully typed:

import type { 
  PayWayClient,
  CreateTransactionParams,
  PayloadBuilderResponse,
  TransactionStatus,
  PaymentOption,
  ExecuteOptions,
  CompletePreAuthParams,
  CompletePreAuthWithPayoutParams,
  CancelPreAuthParams,
  PreAuthResponse,
  PayWayAPIError
} from 'payway-ts';

const params: CreateTransactionParams = {
  amount: 100,
  tran_id: 'ORDER-123',
  currency: 'USD',
  payment_option: 'abapay'
};

const payload: PayloadBuilderResponse = client.buildTransactionPayload(params);

Testing

npm test
npm run test:coverage

Building

npm run build
npm run typecheck

License

MIT License - see LICENSE file for details

Disclaimer

This is an unofficial SDK and is not affiliated with or endorsed by ABA Bank. Use at your own risk.

For ABA PayWay API documentation and support, please contact ABA Bank directly or visit https://www.payway.com.kh/developers/

Author

tykealy

Links

• npm package
• GitHub repository
• Documentation
• Original payway-js package by Seanghay Yath
• ABA Bank
• PayWay Developer Docs