aba-payway 0.1.0 → 0.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024
+Copyright (c) 2026 Joselay
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,16 +1,36 @@
 # aba-payway
 
+[![npm version](https://img.shields.io/npm/v/aba-payway)](https://www.npmjs.com/package/aba-payway)
+[![CI](https://github.com/Joselay/aba-payway/actions/workflows/ci.yml/badge.svg)](https://github.com/Joselay/aba-payway/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm downloads](https://img.shields.io/npm/dm/aba-payway)](https://www.npmjs.com/package/aba-payway)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/aba-payway)
+
 Type-safe TypeScript SDK for [ABA PayWay](https://www.payway.com.kh/) — Cambodia's #1 payment gateway.
 
 > **Unofficial community SDK.** Not affiliated with ABA Bank.
 
+## Why aba-payway?
+
+ABA PayWay's official SDK is a raw REST API with no official Node.js/TypeScript client. That means you're left dealing with manual HMAC hashing, snake_case field ordering, base64 encoding, and zero type safety. This SDK handles all of that for you.
+
+| | `aba-payway` | Rolling your own |
+|---|---|---|
+| Type safety | Full TypeScript with strict types | None — guess the field names |
+| Hash computation | Automatic, correct field ordering | Manual HMAC-SHA512, easy to get wrong |
+| Base64 encoding | Automatic for items, URLs, payout | Do it yourself, hope you didn't miss one |
+| Dependencies | **Zero** — only Node.js built-ins | Probably `axios` + `crypto-js` + glue code |
+| API coverage | 15+ methods | Build each one from scratch |
+| Runtime support | Node.js, Bun, Deno, Cloudflare Workers | Whatever you tested |
+
 ## Features
 
-- Zero runtime dependencies — uses Node.js built-in `crypto` and native `fetch`
-- Full TypeScript support with strict types
-- Dual ESM + CJS output
-- Simple, clean API with camelCase interface
-- Works with Node.js, Bun, Next.js, Express, Hono, and any JS runtime with `fetch`
+- **Zero runtime dependencies** — uses Node.js built-in `crypto` and native `fetch`
+- **Full TypeScript support** with strict types and autocomplete
+- **Dual ESM + CJS output** — works everywhere
+- **15+ API methods** — checkout, QR payments, refunds, pre-auth, payouts, and more
+- **Runs anywhere** — Node.js, Bun, Deno, Next.js, Express, Hono, Cloudflare Workers
+- **Tested against ABA's sandbox** — not just unit tests, real API integration tests
 
 ## Installation
 
@@ -56,7 +76,8 @@ const params = payway.createTransaction({
 |---|---|---|---|---|
 | `merchantId` | `string` | Yes | — | Your ABA PayWay merchant ID |
 | `apiKey` | `string` | Yes | — | Your ABA PayWay API key |
-| `production` | `boolean` | No | `false` | Use production environment |
+| `environment` | `'sandbox' \| 'production'` | No | `'sandbox'` | Target environment |
+| `baseUrl` | `string` | No | — | Override the base URL directly (takes priority over `environment`) |
 
 ### `payway.createTransaction(options)`
 
@@ -96,7 +117,7 @@ Check the status of a transaction.
 ```typescript
 const result = await payway.checkTransaction('order-001')
 console.log(result.status.code)          // '00' = success
-console.log(result.data.payment_status)  // 'APPROVED' | 'DECLINED' | 'PENDING' | ...
+console.log(result.data?.payment_status) // 'APPROVED' | 'DECLINED' | 'PENDING' | ...
 ```
 
 ### `payway.listTransactions(options?)`
@@ -105,8 +126,8 @@ List transactions with optional filters. Max 3-day date range.
 
 ```typescript
 const list = await payway.listTransactions({
-  fromDate: '2025-03-01 00:00:00',
-  toDate: '2025-03-03 23:59:59',
+  fromDate: '2026-03-01 00:00:00',
+  toDate: '2026-03-03 23:59:59',
   status: 'APPROVED',
   page: 1,
   pagination: 20,
@@ -123,6 +144,78 @@ const list = await payway.listTransactions({
 | `page` | `number` | Page number (default: `1`) |
 | `pagination` | `number` | Records per page (default: `40`, max: `1000`) |
 
+### `payway.getTransactionDetails(transactionId)`
+
+Get detailed information about a transaction, including its operation history.
+
+```typescript
+const details = await payway.getTransactionDetails('order-001')
+console.log(details.data?.payment_status)            // 'APPROVED'
+console.log(details.data?.transaction_operations)     // [{ status, amount, ... }]
+```
+
+### `payway.closeTransaction(transactionId)`
+
+Close (cancel) a pending transaction. The payment status becomes `CANCELLED`.
+
+```typescript
+const result = await payway.closeTransaction('order-001')
+console.log(result.status.code) // '00' = success
+```
+
+### `payway.getExchangeRate()`
+
+Fetch the latest exchange rates from ABA Bank for 12 currencies.
+
+```typescript
+const rates = await payway.getExchangeRate()
+console.log(rates.exchange_rates.eur) // { sell: '...', buy: '...' }
+```
+
+### `payway.generateQR(options)`
+
+Generate a dynamic QR code for payment via ABA KHQR, WeChat Pay, or Alipay.
+
+```typescript
+const qr = await payway.generateQR({
+  transactionId: 'qr-001',
+  amount: 10.00,
+  paymentOption: 'abapay_khqr',
+  qrImageTemplate: 'template1',
+  lifetime: 30,
+})
+console.log(qr.qrString)         // QR content string
+console.log(qr.abapay_deeplink)  // ABA Mobile deep link
+```
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `transactionId` | `string` | Yes | Unique transaction ID (max 20 chars) |
+| `amount` | `number` | Yes | Payment amount (min: 100 KHR or 0.01 USD) |
+| `paymentOption` | `QRPaymentOption` | Yes | `abapay_khqr`, `wechat` (USD only), `alipay` (USD only) |
+| `qrImageTemplate` | `string` | Yes | QR image template name |
+| `currency` | `'USD' \| 'KHR'` | No | Default: `'USD'` |
+| `lifetime` | `number` | No | Lifetime in minutes (3–43200) |
+| `firstName` | `string` | No | Payer's first name |
+| `lastName` | `string` | No | Payer's last name |
+| `email` | `string` | No | Payer's email |
+| `phone` | `string` | No | Payer's phone |
+| `purchaseType` | `'purchase' \| 'pre-auth'` | No | Default: `'purchase'` |
+| `items` | `string` | No | Item description (auto base64-encoded) |
+| `callbackUrl` | `string` | No | Payment callback URL (auto base64-encoded) |
+| `returnDeeplink` | `string` | No | Mobile deeplink (auto base64-encoded) |
+| `payout` | `string` | No | Payout JSON string (auto base64-encoded) |
+
+### `payway.getTransactionsByRef(merchantRef)`
+
+Get transactions by merchant reference. Returns up to the last 50 transactions.
+
+```typescript
+const txns = await payway.getTransactionsByRef('REF-001')
+for (const txn of txns.data) {
+  console.log(txn.transaction_id, txn.payment_status)
+}
+
 ## Error Handling
 
 ```typescript
@@ -147,7 +240,7 @@ import { PayWay } from 'aba-payway'
 const payway = new PayWay({
   merchantId: process.env.PAYWAY_MERCHANT_ID!,
   apiKey: process.env.PAYWAY_API_KEY!,
-  production: process.env.NODE_ENV === 'production',
+  environment: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
 })
 
 export async function POST(request: Request) {
@@ -202,6 +295,18 @@ app.post('/pay', (req, res) => {
 
 For the full ABA PayWay API documentation, see [aba-payway-docs](https://github.com/Joselay/aba-payway-docs).
 
+## Contributing
+
+Found a bug or have a feature request? [Open an issue](https://github.com/Joselay/aba-payway/issues) — all feedback is welcome.
+
+Pull requests are also welcome. Please make sure tests pass before submitting:
+
+```bash
+bun run test
+bun run typecheck
+bun run lint
+```
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BASE_URLS: () => BASE_URLS,
   ENDPOINTS: () => ENDPOINTS,
   PRODUCTION_BASE_URL: () => PRODUCTION_BASE_URL,
   PayWay: () => PayWay,
@@ -37,18 +38,27 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/constants.ts
-var SANDBOX_BASE_URL = "https://checkout-sandbox.payway.com.kh";
-var PRODUCTION_BASE_URL = "https://checkout.payway.com.kh";
+var BASE_URLS = {
+  sandbox: "https://checkout-sandbox.payway.com.kh",
+  production: "https://checkout.payway.com.kh"
+};
+var SANDBOX_BASE_URL = BASE_URLS.sandbox;
+var PRODUCTION_BASE_URL = BASE_URLS.production;
 var ENDPOINTS = {
   purchase: "/api/payment-gateway/v1/payments/purchase",
   checkTransaction: "/api/payment-gateway/v1/payments/check-transaction-2",
-  transactionList: "/api/payment-gateway/v1/payments/transaction-list-2"
+  transactionList: "/api/payment-gateway/v1/payments/transaction-list-2",
+  transactionDetail: "/api/payment-gateway/v1/payments/transaction-detail",
+  closeTransaction: "/api/payment-gateway/v1/payments/close-transaction",
+  exchangeRate: "/api/payment-gateway/v1/exchange-rate",
+  generateQR: "/api/payment-gateway/v1/payments/generate-qr",
+  getTransactionsByRef: "/api/payment-gateway/v1/payments/get-transactions-by-mc-ref"
 };
 
 // src/errors.ts
 var PayWayError = class extends Error {
-  constructor(message) {
-    super(message);
+  constructor(message, options) {
+    super(message, options);
     this.name = "PayWayError";
   }
 };
@@ -94,17 +104,24 @@ function formatRequestTime(date = /* @__PURE__ */ new Date()) {
   const seconds = date.getUTCSeconds().toString().padStart(2, "0");
   return `${year}${month}${day}${hours}${minutes}${seconds}`;
 }
-function buildFormData(params) {
-  const formData = new FormData();
+function filterParams(params) {
+  const out = {};
   for (const [key, value] of Object.entries(params)) {
-    if (value !== void 0 && value !== null && value !== "") {
-      formData.append(key, value);
+    if (value !== void 0 && value !== "") {
+      out[key] = value;
     }
   }
+  return out;
+}
+function buildFormData(params) {
+  const formData = new FormData();
+  for (const [key, value] of Object.entries(filterParams(params))) {
+    formData.append(key, String(value));
+  }
   return formData;
 }
 function formatAmount(amount, currency = "USD") {
-  if (currency.toUpperCase() === "KHR") {
+  if (currency === "KHR") {
     return Math.round(amount).toString();
   }
   return amount.toFixed(2);
@@ -118,6 +135,11 @@ var PayWay = class {
   merchantId;
   apiKey;
   baseUrl;
+  timeout;
+  /**
+   * @param config - Merchant credentials and environment selection.
+   * @throws {PayWayConfigError} If `merchantId` or `apiKey` is empty.
+   */
   constructor(config) {
     if (!config.merchantId) {
       throw new PayWayConfigError("merchantId is required");
@@ -127,13 +149,28 @@ var PayWay = class {
     }
     this.merchantId = config.merchantId;
     this.apiKey = config.apiKey;
-    this.baseUrl = config.production ? PRODUCTION_BASE_URL : SANDBOX_BASE_URL;
+    this.baseUrl = config.baseUrl ?? BASE_URLS[config.environment ?? "sandbox"];
+    this.timeout = config.timeout ?? 3e4;
   }
   /**
    * Generate checkout parameters for a transaction.
    * Returns form params to be submitted from the browser via ABA's checkout JS SDK.
    */
   createTransaction(options) {
+    if (!options.transactionId) {
+      throw new PayWayConfigError("transactionId is required");
+    }
+    if (options.transactionId.length > 20) {
+      throw new PayWayConfigError(
+        "transactionId must be at most 20 characters"
+      );
+    }
+    if (options.amount <= 0) {
+      throw new PayWayConfigError("amount must be greater than 0");
+    }
+    if (options.lifetime !== void 0 && (options.lifetime < 3 || options.lifetime > 43200)) {
+      throw new PayWayConfigError("lifetime must be between 3 and 43200");
+    }
     const reqTime = formatRequestTime();
     const currency = options.currency ?? "USD";
     const amount = formatAmount(options.amount, currency);
@@ -170,8 +207,6 @@ var PayWay = class {
       currency,
       options.customFields ?? "",
       options.returnParams ?? "",
-      options.viewType ?? "",
-      options.paymentGate?.toString() ?? "",
       payout,
       options.lifetime?.toString() ?? "",
       options.additionalParams ?? "",
@@ -210,7 +245,15 @@ var PayWay = class {
       payment_gate: options.paymentGate?.toString() ?? ""
     };
   }
+  /**
+   * Check the status of a transaction.
+   * @param transactionId - The unique transaction ID to look up.
+   * @throws {PayWayAPIError} If the API returns a non-2xx response.
+   */
   async checkTransaction(transactionId) {
+    if (!transactionId) {
+      throw new PayWayConfigError("transactionId is required");
+    }
     const reqTime = formatRequestTime();
     const hashValues = [reqTime, this.merchantId, transactionId];
     const hash = createHash(hashValues, this.apiKey);
@@ -225,6 +268,11 @@ var PayWay = class {
       params
     );
   }
+  /**
+   * List transactions with optional filters. Max 3-day date range.
+   * @param options - Filter and pagination options.
+   * @throws {PayWayAPIError} If the API returns a non-2xx response.
+   */
   async listTransactions(options = {}) {
     const reqTime = formatRequestTime();
     const hashValues = [
@@ -256,29 +304,212 @@ var PayWay = class {
       params
     );
   }
-  async request(endpoint, params) {
+  /**
+   * Get detailed information about a transaction, including its operation history.
+   * @param transactionId - The unique transaction ID to look up.
+   * @throws {PayWayAPIError} If the API returns a non-2xx response.
+   */
+  async getTransactionDetails(transactionId) {
+    if (!transactionId) {
+      throw new PayWayConfigError("transactionId is required");
+    }
+    const reqTime = formatRequestTime();
+    const hashValues = [reqTime, this.merchantId, transactionId];
+    const hash = createHash(hashValues, this.apiKey);
+    const params = {
+      hash,
+      tran_id: transactionId,
+      req_time: reqTime,
+      merchant_id: this.merchantId
+    };
+    return this.request(
+      ENDPOINTS.transactionDetail,
+      params,
+      "json"
+    );
+  }
+  /**
+   * Close (cancel) a pending transaction.
+   * @param transactionId - The transaction ID to close.
+   * @throws {PayWayAPIError} If the API returns a non-2xx response.
+   */
+  async closeTransaction(transactionId) {
+    if (!transactionId) {
+      throw new PayWayConfigError("transactionId is required");
+    }
+    const reqTime = formatRequestTime();
+    const hashValues = [reqTime, this.merchantId, transactionId];
+    const hash = createHash(hashValues, this.apiKey);
+    const params = {
+      hash,
+      tran_id: transactionId,
+      req_time: reqTime,
+      merchant_id: this.merchantId
+    };
+    return this.request(
+      ENDPOINTS.closeTransaction,
+      params,
+      "json"
+    );
+  }
+  /**
+   * Fetch the latest exchange rates from ABA Bank.
+   * @throws {PayWayAPIError} If the API returns a non-2xx response.
+   */
+  async getExchangeRate() {
+    const reqTime = formatRequestTime();
+    const hashValues = [reqTime, this.merchantId];
+    const hash = createHash(hashValues, this.apiKey);
+    const params = {
+      hash,
+      req_time: reqTime,
+      merchant_id: this.merchantId
+    };
+    return this.request(
+      ENDPOINTS.exchangeRate,
+      params,
+      "json"
+    );
+  }
+  /**
+   * Generate a QR code for payment via ABA KHQR, WeChat Pay, or Alipay.
+   * @param options - QR generation options.
+   * @throws {PayWayConfigError} If required options are missing or invalid.
+   * @throws {PayWayAPIError} If the API returns a non-2xx response.
+   */
+  async generateQR(options) {
+    if (!options.transactionId) {
+      throw new PayWayConfigError("transactionId is required");
+    }
+    if (options.amount <= 0) {
+      throw new PayWayConfigError("amount must be greater than 0");
+    }
+    if (!options.paymentOption) {
+      throw new PayWayConfigError("paymentOption is required");
+    }
+    if (!options.qrImageTemplate) {
+      throw new PayWayConfigError("qrImageTemplate is required");
+    }
+    if (options.lifetime !== void 0 && (options.lifetime < 3 || options.lifetime > 43200)) {
+      throw new PayWayConfigError("lifetime must be between 3 and 43200");
+    }
+    const reqTime = formatRequestTime();
+    const currency = options.currency ?? "USD";
+    const amount = formatAmount(options.amount, currency);
+    const items = options.items ? toBase64(options.items) : "";
+    const callbackUrl = options.callbackUrl ? toBase64(options.callbackUrl) : "";
+    const returnDeeplink = options.returnDeeplink ? toBase64(options.returnDeeplink) : "";
+    const customFields = options.customFields ? toBase64(options.customFields) : "";
+    const payout = options.payout ? toBase64(options.payout) : "";
+    const hashValues = [
+      reqTime,
+      this.merchantId,
+      options.transactionId,
+      amount,
+      items,
+      options.firstName ?? "",
+      options.lastName ?? "",
+      options.email ?? "",
+      options.phone ?? "",
+      options.purchaseType ?? "",
+      options.paymentOption,
+      callbackUrl,
+      returnDeeplink,
+      currency,
+      customFields,
+      options.returnParams ?? "",
+      payout,
+      options.lifetime?.toString() ?? "",
+      options.qrImageTemplate
+    ];
+    const hash = createHash(hashValues, this.apiKey);
+    const params = {
+      hash,
+      req_time: reqTime,
+      merchant_id: this.merchantId,
+      tran_id: options.transactionId,
+      amount: options.amount,
+      currency,
+      payment_option: options.paymentOption,
+      lifetime: options.lifetime,
+      qr_image_template: options.qrImageTemplate,
+      first_name: options.firstName,
+      last_name: options.lastName,
+      email: options.email,
+      phone: options.phone,
+      purchase_type: options.purchaseType,
+      items: items || void 0,
+      callback_url: callbackUrl || void 0,
+      return_deeplink: returnDeeplink || void 0,
+      custom_fields: customFields || void 0,
+      return_params: options.returnParams,
+      payout: payout || void 0
+    };
+    return this.request(
+      ENDPOINTS.generateQR,
+      params,
+      "json"
+    );
+  }
+  /**
+   * Get transactions by merchant reference. Returns up to the last 50 transactions.
+   * @param merchantRef - Your merchant reference number.
+   * @throws {PayWayAPIError} If the API returns a non-2xx response.
+   */
+  async getTransactionsByRef(merchantRef) {
+    if (!merchantRef) {
+      throw new PayWayConfigError("merchantRef is required");
+    }
+    const reqTime = formatRequestTime();
+    const hashValues = [reqTime, this.merchantId, merchantRef];
+    const hash = createHash(hashValues, this.apiKey);
+    const params = {
+      hash,
+      merchant_ref: merchantRef,
+      req_time: reqTime,
+      merchant_id: this.merchantId
+    };
+    return this.request(
+      ENDPOINTS.getTransactionsByRef,
+      params,
+      "json"
+    );
+  }
+  async request(endpoint, params, format = "form") {
     const url = `${this.baseUrl}${endpoint}`;
-    const formData = new FormData();
-    for (const [key, value] of Object.entries(params)) {
-      if (value !== void 0 && value !== null && value !== "") {
-        formData.append(key, value);
-      }
+    let body;
+    const headers = {};
+    if (format === "json") {
+      body = JSON.stringify(filterParams(params));
+      headers["Content-Type"] = "application/json";
+    } else {
+      body = buildFormData(params);
+    }
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        body,
+        headers,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+    } catch (error) {
+      throw new PayWayError(
+        error instanceof Error ? error.message : "Network request failed",
+        { cause: error }
+      );
     }
-    const response = await fetch(url, {
-      method: "POST",
-      body: formData
-    });
     if (!response.ok) {
       const text = await response.text();
-      let body = text;
+      let responseBody = text;
       try {
-        body = JSON.parse(text);
+        responseBody = JSON.parse(text);
       } catch {
       }
       throw new PayWayAPIError(
         `PayWay API error: ${response.status} ${response.statusText}`,
         response.status,
-        body
+        responseBody
       );
     }
     return await response.json();
@@ -286,6 +517,7 @@ var PayWay = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BASE_URLS,
   ENDPOINTS,
   PRODUCTION_BASE_URL,
   PayWay,