aba-payway

Type-safe TypeScript SDK for ABA PayWay — 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 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

# bun
bun add aba-payway

# npm
npm install aba-payway

# pnpm
pnpm add aba-payway

Quick Start

import { PayWay } from 'aba-payway'

const payway = new PayWay({
  merchantId: 'your_merchant_id',
  apiKey: 'your_api_key',
})

// Generate checkout params (synchronous — no API call)
const params = payway.createTransaction({
  transactionId: 'order-001',
  amount: 10.00,
  items: 'Product A',
  returnUrl: 'https://yoursite.com/callback',
})

// Send `params` to your frontend, populate ABA's hidden form,
// and call AbaPayway.checkout() to open the payment dialog.
// See examples/ for more snippets and framework integrations.

API Reference

new PayWay(config)

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | merchantId | string | Yes | — | Your ABA PayWay merchant ID | | apiKey | string | Yes | — | Your ABA PayWay API key | | environment | 'sandbox' \| 'production' | No | 'sandbox' | Target environment | | baseUrl | string | No | — | Override the base URL directly (takes priority over environment) |

payway.createTransaction(options)

Generate checkout parameters for a payment. Synchronous — computes the HMAC hash and returns form params without making any API calls.

Returns CheckoutParams — snake_case form parameters to submit via ABA's checkout JS SDK.

| Parameter | Type | Required | Description | |---|---|---|---| | transactionId | string | Yes | Unique transaction ID (max 20 chars) | | amount | number | Yes | Purchase amount | | currency | 'USD' \| 'KHR' | No | Default: 'USD' | | paymentOption | PaymentOption | No | cards, abapay_khqr, abapay_khqr_deeplink, alipay, wechat, google_pay | | firstName | string | No | Buyer's first name | | lastName | string | No | Buyer's last name | | email | string | No | Buyer's email | | phone | string | No | Buyer's phone | | items | string \| ItemEntry[] | No | Item description — string or { name, quantity, price }[] | | returnUrl | string | No | Callback URL for payment completion | | cancelUrl | string | No | Redirect URL when user closes payment | | continueSuccessUrl | string | No | Redirect URL after success | | type | 'purchase' \| 'pre-auth' | No | Default: 'purchase' | | shipping | number | No | Shipping fee | | viewType | string | No | 'hosted_view' or 'popup' | | lifetime | number | No | Payment lifetime in minutes (3–43200) | | skipSuccessPage | number | No | 0 (don't skip) or 1 (skip) | | payout | string | No | Payout details (JSON string) | | returnDeeplink | string | No | Mobile app deeplink | | googlePayToken | string | No | Required if paymentOption is 'google_pay' |

items, returnUrl, returnDeeplink, and payout are automatically base64-encoded by the SDK.

payway.checkTransaction(transactionId)

Check the status of a transaction.

const result = await payway.checkTransaction('order-001')
console.log(result.status.code)          // '00' = success
console.log(result.data?.payment_status) // 'APPROVED' | 'DECLINED' | 'PENDING' | ...

payway.listTransactions(options?)

List transactions with optional filters. Max 3-day date range.

const list = await payway.listTransactions({
  fromDate: '2026-03-01 00:00:00',
  toDate: '2026-03-03 23:59:59',
  status: 'APPROVED',
  page: 1,
  pagination: 20,
})

| Parameter | Type | Description | |---|---|---| | fromDate | string | Start date: 'YYYY-MM-DD HH:mm:ss' | | toDate | string | End date: 'YYYY-MM-DD HH:mm:ss' | | fromAmount | number | Minimum amount filter | | toAmount | number | Maximum amount filter | | status | string | Comma-separated: APPROVED, DECLINED, PENDING, PRE-AUTH, CANCELLED, REFUNDED | | 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.

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.

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.

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.

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.

const txns = await payway.getTransactionsByRef('REF-001')
for (const txn of txns.data) {
  console.log(txn.transaction_id, txn.payment_status)
}

## Error Handling

```typescript
import { PayWay, PayWayAPIError, PayWayConfigError } from 'aba-payway'

| Error Class | When Thrown | |---|---| | PayWayConfigError | Missing or invalid constructor config | | PayWayAPIError | ABA API returns non-2xx response (has statusCode and responseBody properties) | | PayWayError | Base error class | | PayWayHashError | Hash generation failure |

Framework Examples

Next.js (App Router)

// app/api/pay/route.ts
import { PayWay } from 'aba-payway'

const payway = new PayWay({
  merchantId: process.env.PAYWAY_MERCHANT_ID!,
  apiKey: process.env.PAYWAY_API_KEY!,
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
})

export async function POST(request: Request) {
  const { orderId, amount } = await request.json()

  const params = payway.createTransaction({
    transactionId: orderId,
    amount,
    items: 'Order payment',
    returnUrl: `${process.env.NEXT_PUBLIC_URL}/api/pay/callback`,
  })

  return Response.json(params)
}

Express

import express from 'express'
import { PayWay } from 'aba-payway'

const app = express()
app.use(express.json())

const payway = new PayWay({
  merchantId: process.env.PAYWAY_MERCHANT_ID!,
  apiKey: process.env.PAYWAY_API_KEY!,
})

app.post('/pay', (req, res) => {
  const params = payway.createTransaction({
    transactionId: req.body.orderId,
    amount: req.body.amount,
    items: 'Order payment',
    returnUrl: 'https://yoursite.com/callback',
  })
  res.json(params)
})

Sandbox Test Cards

| Card | Number | Expiry | CVV | Result | |---|---|---|---|---| | Mastercard | 5156 8399 3770 6777 | 01/30 | 993 | Approved | | Visa | 4286 0900 0000 0206 | 04/30 | 777 | Approved | | Mastercard | 5156 8302 7256 1029 | 04/30 | 777 | Declined | | Visa | 4156 8399 3770 6777 | 01/30 | 993 | Declined |

Documentation

For the full ABA PayWay API documentation, see aba-payway-docs.

Contributing

Found a bug or have a feature request? Open an issue — all feedback is welcome.

Pull requests are also welcome. Please make sure tests pass before submitting:

bun run test
bun run typecheck
bun run lint

License

MIT