koma-khqr

Framework-friendly KHQR checkout package for Koma.

Install

npm install koma-khqr

Status

• 8 Node-family framework targets supported
• 7 npm entrypoints
• runnable in-repo examples for every supported target
• live checkout-session creation verified across all supported framework targets
• only the on-device bank scan remains manual if you want payment-completion proof
• Spring Boot, Python, and Laravel are public ecosystem notes only and are marked coming soon

Standard Env

Use the same server-side env names across frameworks:

KOMA_API_URL=https://koma.khqr.site
KOMA_MERCHANT_ID=your-merchant-id@bankcode
KOMA_SECRET_KEY=replace-with-your-secret-key
KOMA_APP_URL=http://localhost:3000

Rules:

• KOMA_SECRET_KEY stays on the server only
• KOMA_APP_URL is the standard app base URL
• NEXT_PUBLIC_APP_URL still works as a legacy fallback for older setups
• use the same four env names in every framework sandbox and example

Node Runtime Support

• Node 18+ is the practical floor for the package runtime today
• Node 20.9+ is required for the Next.js path in this repo because next@16 requires it
• Node 16 is not a supported target for the current server adapters and example stack

Use framework-support-checklist.md for the exact per-framework matrix.

Legacy Config Compatibility

Older setups still work with compatibility fallbacks:

• NEXT_PUBLIC_APP_URL still resolves as the app base URL fallback
• merchantId is still accepted on KhqrCheckout for display compatibility
• deprecated client props like secretKey, apiBaseUrl, successUrl, and cancelUrl are still tolerated by KhqrCheckout, but browser-side signing is no longer used

Package Surface

• koma-khqr exposes the default React client entrypoint.
• koma-khqr/react exposes the React client entrypoint directly.
• koma-khqr/next exposes Next.js route factories and config helpers.
• koma-khqr/express exposes a ready-made Express router for client-only frontends.
• koma-khqr/server exposes lower-level signing, checkout, parsing, and polling helpers.
• koma-khqr/vue exposes Vue-oriented config helpers for server-backed setups.
• koma-khqr/angular exposes Angular-oriented config helpers for server-backed setups.

Simple mental model:

• koma-khqr/next for Next.js
• koma-khqr/react for React UI
• koma-khqr/express for React, Vue, Angular, or other client-only frontends with a Node backend
• koma-khqr/server for custom backend logic
• koma-khqr/vue and koma-khqr/angular for framework-specific config helpers

When You Need Express Or dotenv

• You do not install express for Next.js, Nuxt, or other full-stack frameworks just to use koma-khqr.
• You use express when your frontend is client-only and still needs a small Node backend for secure signing and polling routes.
• You do not need dotenv if your framework already loads env vars for you.
• You use dotenv only in plain Node entry files such as server.mjs when you want local .env or .env.local loading during development.
• In the runnable examples, these platform packages are already declared in each example app's package.json, so npm install inside that example is enough.

Choose Your Framework

Next.js

• TypeScript guide: next-typescript.md
• JavaScript guide: next-javascript.md
• Public example overview: example-apps.md

React + Vite

• TypeScript guide: react-vite-typescript.md
• JavaScript guide: react-vite-javascript.md
• Public example overview: example-apps.md

React

• Guide: react.md
• Public example overview: example-apps.md

Vue / Nuxt

• Vue guide: vue.md
• Nuxt guide: nuxt.md
• Public example overview: example-apps.md

Express / NestJS

• Express guide: express.md
• NestJS guide: nest.md
• Public example overview: example-apps.md

Angular

• Guide: angular.md
• Public example overview: example-apps.md

Spring / Python / Laravel

• First setup: first-setup.md
• Spring Boot: spring.md
• Python: python.md
• Laravel: laravel.md
• Public example overview: example-apps.md

Testing

• Automated status: all 8 Node-family framework targets have runnable examples and live checkout-session verification.
• Manual-only final step: scan and complete one real payment on-device if you want bank-confirmed completion evidence.
• Matrix: testing-matrix.md
• Support checklist: framework-support-checklist.md
• Sandbox guide: sandbox-testing.md
• WebContainer sandboxes: webcontainer-sandboxes.md
• First setup: first-setup.md

Quick Start

Client

import { KhqrCheckout } from "koma-khqr/react";

export default function ProductCard() {
  return (
    <KhqrCheckout
      amount="12"
      currency="USD"
      expiresInSeconds={120}
      productId="P001"
      productName="Cambodian Coffee Blend"
      renderMode="direct"
    />
  );
}

expiresInSeconds is optional for direct checkout mode. Use it when you want the QR card countdown to last longer than the default 30 seconds, for example 120 for 2:00.

Next.js Server

import { createKomaNext } from "koma-khqr/next";

export const koma = createKomaNext();

Then your routes stay short:

export const POST = koma.qr;

Client-Only Backend

import express from "express";
import { createKomaExpress } from "koma-khqr/express";

const app = express();

app.use(express.json());
app.use(
  createKomaExpress({
    appBaseUrl: "http://localhost:5173",
  }),
);

Vue / Angular Config Helpers

import { createKomaVueConfig } from "koma-khqr/vue";
import { createKomaAngularConfig } from "koma-khqr/angular";

const vueConfig = createKomaVueConfig();
const angularConfig = createKomaAngularConfig();

Standard Flow

Every complete integration should include:

• a checkout page
• a QR creation route
• a polling route
• /payment/success
• /payment/cancelled

That flow is documented in the framework guides above.

Security

• never generate the checkout hash in the browser
• never expose KOMA_SECRET_KEY to the client
• React Server Components still need a real server runtime to own secrets and outbound Koma requests
• rotate any credential that has been pasted into chat or committed accidentally

Provider Notes

Checkout hash payload order:

continueSuccessURL + returnURL + currency + tranID + merchantId + amount

The package signs this using HMAC-SHA512(secretKey, payload) and base64-encodes the digest.

Extra References

• framework-recipes.md
• pi-integration.md
• example-apps.md