payway-kh

Unofficial ABA PayWay API wrapper for JavaScript, TypeScript, and Python. Works everywhere: Node.js, React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, Remix, Bun, Deno, and plain browser <script> tags.

Installation

npm install payway-kh
# or
yarn add payway-kh
# or
pnpm add payway-kh

Framework Compatibility

| Environment | Supported | Import style | |-------------|-----------|--------------| | Node.js 18+ | ✅ | require() or import | | Next.js (server) | ✅ | import | | React (via API route) | ✅ | use server-side only | | Vue 3 / Nuxt | ✅ | import | | Svelte / SvelteKit | ✅ | import | | Astro | ✅ | import in .astro server | | Remix | ✅ | import in loader/action | | Bun | ✅ | import | | Deno | ✅ | import from npm:payway-kh | | Browser CDN | ✅ | <script> UMD + PayWayKH.* | | TypeScript | ✅ | full types included | | Plain JS (no TS) | ✅ | JSDoc IntelliSense via .d.ts |

Quick Start

Just provide a payment link and amount - the package handles everything else!

const { PayWayClient } = require('payway-kh')
// or: import { PayWayClient } from 'payway-kh'

const client = new PayWayClient()

// Step 1: Create QR with just link and amount
const qr = await client.createQR({
  url: 'https://link.payway.com.kh/ABAPAYr1436868d',
  amount: 0.01
})

// Step 2: Wait for payment (auto-polls until paid)
const result = await client.waitForPayment({
  interval: 3000, // check every 3 seconds
  timeout: 300000, // 5 minute timeout
  onUpdate: (status) => {
    if (status.meta.qr_scanned) console.log('QR scanned!')
    if (status.meta.payment_approved) console.log('Payment approved!')
  }
})

console.log('Payment complete!', result)

API

new PayWayClient(options?)

Creates a new PayWay client.

const client = new PayWayClient({
  baseUrl: 'https://2008.site/payway' // optional, this is the default
})

client.createQR(request)

Creates a payment QR code. Transaction details are automatically stored for easy status checking.

const qr = await client.createQR({
  url: string,    // PayWay payment link
  amount: number  // Amount in currency units
})

// Returns:
// {
//   qr_string: string,
//   expire_in_sec: string,
//   download_qr: string,
//   transaction_summary: { merchant: MerchantInfo, order_details: OrderDetails },
//   status: PayWayStatus,
//   client_id: string
// }

client.checkStatus(request?)

Checks payment status. Uses stored transaction details from createQR() if no arguments provided.

// Simplified - uses stored transaction details
const status = await client.checkStatus()

// Or provide explicitly:
const status = await client.checkStatus({
  tran_id: string,
  client_id: string
})

// Returns:
// {
//   status: PayWayStatus,
//   data: Record<string, unknown>,
//   meta: {
//     tran_id: string,
//     client_id: string,
//     qr_scanned: boolean,      // true when customer scans QR
//     payment_approved: boolean, // true when payment is approved
//     finished: boolean         // true when transaction is complete
//   }
// }

client.waitForPayment(options?)

Polls checkStatus() until payment is complete. Payment is ONLY successful when ALL three conditions are true:

• qr_scanned = true (customer scanned QR)
• payment_approved = true (payment approved)
• finished = true (transaction complete)

⚠️ QR scanned alone ≠ success! Payment approved alone ≠ success! ALL 3 must be true!

const result = await client.waitForPayment({
  interval: 3000,   // poll interval in ms (default: 3000)
  timeout: 300000,  // max wait time in ms (default: 300000 = 5 min)
  onUpdate: (status) => console.log(status) // callback on each check
})

client.health()

Checks API health.

const health = await client.health()
// { status: 'ok', upstream: { status: string, timestamp: string } }

Error Handling

const { PayWayClient, PayWayError } = require('payway-kh')

try {
  await client.createQR({ url: '...', amount: 0.01 })
} catch (err) {
  if (err instanceof PayWayError) {
    // err.code: 'INVALID_INPUT' | 'UPSTREAM_ERROR' | 'NETWORK_ERROR'
    // err.message: human-readable error
    // err.statusCode: HTTP status code (if applicable)
    console.error(`[${err.code}] ${err.message}`)
  }
}

Examples

See the examples/ folder:

• node-cjs.js - Node.js with require()
• node-esm.mjs - Node.js with import
• nextjs-route.ts - Next.js API route
• vue-composable.ts - Vue 3 composable
• browser-cdn.html - Plain browser <script> tag

Browser CDN Usage

<script src="https://unpkg.com/payway-kh/dist/index.umd.js"></script>
<script>
  const client = new PayWayKH.PayWayClient()
  client.health().then(console.log)
</script>

⚠️ Security Note

Never call PayWay directly from React/Vue client components - always proxy through your own backend API route. The client should only be used server-side.

Node.js 16 Support

This package uses native fetch (Node 18+). For Node 16, add a polyfill:

import fetch from 'node-fetch'
global.fetch = fetch

GitHub Repository

git clone https://github.com/blaxkmiradev/payway-kh.git
cd payway-kh
npm install
npm run build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Issues

Found a bug or have a feature request? Please file an issue at GitHub Issues.

License

MIT

Author

rikixz - GitHub

⭐ Star this repo if you find it useful! Unofficial ABA PayWay wrapper - Free & Open Source for everyone.