ຈາກການເຊື່ອມຕໍ່ API
ສູ່ການອອກປີ້ທີ່ຖືກຕ້ອງ.

1. ເລືອກປີ້

   Browser ສົ່ງ product, quantity, visitDate; ບໍ່ກຳນົດຍອດເງິນ.

2. ສ້າງ order & sign

   Ticket ຄຳນວນລາຄາຝັ່ງ server, ບັນທຶກ order ແລະ idempotency, ລົງ RSA signature.

3. ຂໍ QR ຈາກ EASYPOS

   Backend POST new-transaction; ຮັບ transactionId, qrCode string ແລະ expiredTime.

4. ສະແກນ & ຊຳລະ

   Browser render string ເປັນຮູບ QR; ລູກຄ້າສະແກນຜ່ານ bank app.

5. ກວດ webhook → PAID

   EASYPOS ສົ່ງ PAYMENT_CONFIRMED; Ticket ກວດ HMAC/ຂໍ້ມູນ ແລະບັນທຶກຄັ້ງດຽວ.

6. ອອກປີ້ & ກວດເຂົ້າ

   Browser ອ່ານສະຖານະ order; ປີ້ທີ່ຢືນຢັນແລ້ວໃຊ້ເຂົ້າໄດ້ຄັ້ງດຽວ.

1. ເຂົ້າ EASYPOS Portal ↗ → Payment gateway → Partners. ເລືອກ Partner ທີ່ຕ້ອງການ; ສ້າງ draft ສະເພາະ partner ໃໝ່.
2. ລະບຸຊື່ທຸລະກິດ, email, merchant binding ແລະ permissions ທີ່ຈຳເປັນ. ໃຫ້ provider ກວດ outbound IP ທີ່ API ເຫັນຈິງ; ບໍ່ຄາດເດົາຈາກ DNS ຫຼື IP ໃນ Docker.
3. ລົງທະບຽນ public key → ກຽມ HTTPS webhook → ຕັ້ງ secret → Challenge/Test. ການ Activate Partner ແຍກຈາກ Activate key.
4. ກວດ live policy ຫຼັງ approval: ACTIVE, Create transactions, Receive webhook, key ແລະ endpoint readiness. ຄ່າ Draft ບໍ່ຮັບປະກັນວ່າ Live ໃຊ້ແລ້ວ.

ເບິ່ງຮູບ Portal: Login

ປຸ່ມ ແລະສິດອາດຕ່າງກັນຕາມ role. ໜ້ານີ້ບໍ່ປ່ຽນ IP allowlist, network policy, secret ຫຼື key ໃດໆ.

# Example only: create NEW demo keys; never overwrite the active key.
umask 077
key_dir=$(mktemp -d ./partner-key-demo.XXXXXX)
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out "$key_dir/partner-private.pem"
openssl pkey -in "$key_dir/partner-private.pem" -pubout -out "$key_dir/partner-public.pem"
openssl pkey -pubin -in "$key_dir/partner-public.pem" -outform DER | openssl dgst -sha256
# Upload ONLY partner-public.pem. Keep the private file server-side, mode 0600.

PEM ທີ່ upload ຕ້ອງເລີ່ມ -----BEGIN PUBLIC KEY-----. Fingerprint ແມ່ນ SHA-256 hex ຂອງ DER SubjectPublicKeyInfo; ບໍ່ແມ່ນ hash ຂໍ້ຄວາມ PEM.

1. Partners → ເລືອກ Partner → Key lifecycle → ປ້ອນ public PEM, effective/expiry ແລະ audit reason.
2. Validate only → ກວດ fingerprint → Upload pending key. ຂັ້ນນີ້ຍັງບໍ່ Activate.
3. Activate ເມື່ອ backend ກຽມ key ຄູ່ກັນແລ້ວ ແລະໄດ້ອະນຸມັດ. ການ rotate ຕ້ອງມີ grace/rollback plan; ຢ່າແທນ key ເກົ່າໂດຍບໍ່ກວດ retries ຄ້າງ.

Canonical request · ລຽງຕາມນີ້

easypay-partner-v1
<exact X-Partner-Timestamp>
<exact X-Partner-Nonce>
<compact JSON body>

ຕໍ່ແຕ່ລະແຖວດ້ວຍ LF (\n), UTF-8, ບໍ່ມີ newline ທ້າຍ. ສົ່ງ body string ດຽວກັບທີ່ sign; ຫ້າມ pretty-print ຫຼື serialize ໃໝ່ຫຼັງ sign.

import { sign, constants, randomUUID } from "node:crypto";

// Server-side only. Input order/price must already be validated and persisted.
export function prepareSignedRequest(payload, privateKey, fingerprint, operationKey) {
  const timestamp = new Date().toISOString();
  const nonce = randomUUID().replaceAll("-", "");
  const body = JSON.stringify(payload);
  const canonical = ["easypay-partner-v1", timestamp, nonce, body].join("\n");
  const signature = sign("RSA-SHA1", Buffer.from(canonical, "utf8"), {
    key: privateKey, padding: constants.RSA_PKCS1_PADDING
  }).toString("base64");
  return { body, headers: {
    "Content-Type": "application/json",
    "X-Partner-Timestamp": timestamp, "X-Partner-Nonce": nonce,
    "X-Key-Fingerprint": fingerprint, "X-Signature": signature,
    "X-Idempotency-Key": operationKey, "X-Correlation-ID": "corr-" + randomUUID()
  }};
}
// No fetch here. Persist this exact envelope before an authorized send.

{
  "productId": "YOUR_PRODUCT_ID",
  "productRevision": 1,
  "quantity": 1,
  "visitDate": "2026-10-01"
}

ໃຊ້ຈາກ backend ເທົ່ານັ້ນ. ຢືນຢັນ environment ກັບ EASYPOS; ຄຳວ່າ UAT ບໍ່ຮັບປະກັນ sandbox ແລະ QR ອາດເປັນເງິນຈິງ.

// Server-side illustration ONLY. No call is made by this guide.
// envelope is the persisted output of prepareSignedRequest.
export async function sendOnce(envelope, approved = false) {
  if (!approved) throw new Error("OUTBOUND_NOT_APPROVED");
  const response = await fetch(
    "https://api.qrlaos.com/payment/api/PaymentQr/new-transaction",
    { method: "POST", headers: envelope.headers, body: envelope.body,
      redirect: "error", signal: AbortSignal.timeout(12000) }
  );
  return { status: response.status, text: await response.text() };
}
// No automatic retries. Validate/classify the response before saving a QR.
// Timeout/unknown outcome -> REVIEW/reconcile, not a new payment.
// Caller must enforce authorization, mode, freshness and idempotency guards.

Request headers

Request body

{
  "uuid": "P0000000000001",
  "partnerId": "YOUR_PARTNER_ID",
  "amount": 30000,
  "description": "Kuang Si admission",
  "expiryTime": 15,
  "merchantId": "YOUR_MERCHANT_ID",
  "platform": "IOS",
  "mobileNum": "2000000000",
  "currency": "LAK"
}

30,000 LAK ແມ່ນຕົວຢ່າງອະທິບາຍ, ບໍ່ແມ່ນລາຄາ catalog ປັດຈຸບັນ. ເກັບ unit price/revision ໃນ order ກ່ອນເອີ້ນ provider; ບໍ່ເຊື່ອ amount ຈາກ browser.

{
  "success": true,
  "transactionId": "EXAMPLE_TRANSACTION_ID",
  "qrCode": "EXAMPLE_ONLY_NOT_A_PAYABLE_QR",
  "expiredTime": "2026-09-18T03:15:00Z",
  "amount": 30000,
  "uuid": "P0000000000001"
}

Response ອາດມີ id, code, message ເພີ່ມ. Adapter ຕ້ອງ validate success, transaction ID, QR string, expiry ແລະຂໍ້ມູນ order; HTTP 200 ຢ່າງດຽວບໍ່ພໍ.

import QRCode from "qrcode";
// qrCode comes from the validated, persisted provider response.
const imageUrl = await QRCode.toDataURL(qrCode, {
  width: 300, margin: 2, errorCorrectionLevel: "M"
});
// Render <img src={imageUrl} alt="Payment QR" />.
// Do NOT encode the whole JSON, transaction ID, or order URL.

ບໍ່ໃຊ້ third-party QR image service ເພາະຈະສົ່ງ payment payload ອອກຂ້າງນອກ. ຖ້າບໍ່ມີ QR string ຢ່າສ້າງ QR ປອມ; ສະແດງ pending/failed/review ຕາມຂໍ້ເທັດຈິງ.

Portal → Partner → Webhook setup: ຕັ້ງ HTTPS endpoint ຂອງ server, ກວດ retry policy ແລະ audit reason. ຜູ້ມີສິດກຽມ secret ຜ່ານ protected channel ໃຫ້ backend ແລ້ວຈຶ່ງ Challenge/Test. ຢ່າ rotate secret ທີ່ໃຊ້ງານຢູ່ເພື່ອອ່ານຄ່າຄືນ.

{
  "Content-Type": "application/json",
  "X-EasyPay-Webhook-Id": "pwh-123",
  "X-EasyPay-Webhook-Timestamp": "2026-09-18T03:01:00.000Z",
  "X-EasyPay-Webhook-Signature-Version": "easypay-webhook-v1",
  "X-EasyPay-Webhook-Signature": "sha256=<64 lowercase hex characters>"
}

{
  "eventType": "PAYMENT_CONFIRMED",
  "deliveryId": "pwh-123",
  "timestamp": "2026-09-18T03:01:00.000Z",
  "replayProtected": true,
  "data": {
    "uuid": "P0000000000001",
    "amount": 30000,
    "billId": "EXAMPLE_TRANSACTION_ID",
    "currency": "LAK",
    "partnerId": "YOUR_PARTNER_ID",
    "paymentAt": "2026-09-18T03:00:50.000000Z",
    "paidStatus": "FNLD",
    "paymenBank": "LDB"
  }
}

easypay-webhook-v1
<deliveryId>
<exact timestamp header>
<eventType>
<lowercase SHA256 hex of raw UTF-8 body>

HMAC-SHA256 ໃຊ້ UTF-8 bytes ຂອງ secret ໂດຍກົງ (ບໍ່ base64-decode). Output: sha256=<lowercase hex>. ຮັກສາ raw body ກ່ອນ JSON parsing; ບໍ່ hash JSON ທີ່ serialize ໃໝ່.

import { createHash, createHmac, timingSafeEqual } from "node:crypto";

// CRYPTO CHECK ONLY: also apply the validation/DB gates listed below.
export function matchesHmac(rawBody, deliveryId, timestamp, eventType, signature, secret) {
  if (!/^sha256=[a-f0-9]{64}$/.test(signature)) return false;
  const digest = createHash("sha256").update(rawBody, "utf8").digest("hex");
  const canonical = ["easypay-webhook-v1", deliveryId, timestamp, eventType, digest].join("\n");
  const expected = createHmac("sha256", Buffer.from(secret, "utf8"))
    .update(canonical, "utf8").digest();
  return timingSafeEqual(Buffer.from(signature.slice(7), "hex"), expected);
}

ກວດຄົບກ່ອນຕອບ 200

1. ກວດ trusted ingress/source policy ທີ່ມີຢູ່; ບໍ່ເຊື່ອ forwarded headers ຈາກ client ໂດຍກົງ.
2. ຈຳກັດ body 16 KiB ແລະ request time. ກວດ schema, version, exact header/body IDs, UTC timestamp (Ticket ໃຊ້ ±15 ນາທີ) ແລະ timing-safe HMAC.
3. ກວດ partner/payment/reference/amount/currency/FNLD; ບໍ່ອະນຸມັດລາຍການບໍ່ຮູ້ຈັກ ຫຼືຂໍ້ມູນຂັດກັນ.
4. Database unique/dedupe ຕາມ delivery ID ແລະ payment identity; atomic transaction ສຳລັບ receipt + PAID + ticket. Duplicate ທີ່ກົງກັນຕອບ 200 ໂດຍບໍ່ອອກປີ້ໃໝ່.
5. Commit ສຳເລັດຈຶ່ງ acknowledge {"received":true,"duplicate":false}. DB ລົ້ມເຫຼວບໍ່ຕອບວ່າຮັບແລ້ວ.

{
  "eventType": "PARTNER_WEBHOOK_CHALLENGE",
  "deliveryId": "00000000-0000-4000-8000-000000000001",
  "timestamp": "2026-09-18T03:01:00.000Z",
  "replayProtected": true,
  "challenge": "0123456789abcdef0123456789abcdef"
}

{
  "eventType": "PARTNER_WEBHOOK_TEST",
  "deliveryId": "00000000-0000-4000-8000-000000000001",
  "timestamp": "2026-09-18T03:01:00.000Z",
  "replayProtected": true,
  "challenge": null
}

ເກັບ correlation ID, UTC start/end, HTTP status, exception name/code, UTF-8 byte count ແລະ SHA-256 ຂອງ request body. ຢ່າ log password/private key/webhook secret/token/signature ຫຼື QR payload ແບບເປີດສາທາລະນະ. ການເພີ່ມ timeout ຢ່າງດຽວບໍ່ໄດ້ພິສູດວ່າ transport ຖືກແກ້.

• Local PostgreSQL ແຍກ test DB, mock adapter ແລະ test keys; ບລັອກ external network ໃນ tests.
• Tests ສຳລັບ signature/body tampering/time, mismatch, duplicate/concurrency, 503/restart, atomic receipt/PAID/ticket ແລະປີ້ໃຊ້ຊ້ຳ.
• Versioned artifact, schema migration ຮັກສາຂໍ້ມູນ, backup/rollback. Secrets ຢູ່ protected file/secret store, ບໍ່ໃນ image/Git/NEXT_PUBLIC/localStorage.
• Deploy receiver ໃສ່ server HTTPS ເດີມ; ບໍ່ຈຳເປັນ tunnel ເຂົ້າ Mac. ກວດ health, signature rejection, source identity ແລະ live policy ແບບ read-only.
• ໃຫ້ EASYPOS ຢືນຢັນ normal signed delivery, secret decrypt, retry/monitoring; synthetic test ຕ້ອງມີ fixture, budget ແລະ stop conditions.
• ເງິນຈິງຕ້ອງອະນຸມັດ amount/payer/ການແກ້ໄຂຍອດ; ກວດ QR → ຍອດຈ່າຍ → webhook → PAID → ປີ້ → ກວດເຂົ້າ. Mock PASS ບໍ່ເທົ່າ production-ready.
• ກ່ອນໃຊ້ງານສາທາລະນະ ຄວນມີ authentication/RBAC ສຳລັບປ່ຽນລາຄາ, ກວດເຂົ້າ ແລະຂໍ້ມູນທຸລະກຳ. Anonymous admin ຂອງ demo ບໍ່ແມ່ນ security pattern ທີ່ຄວນນຳໄປໃຊ້ຈິງ.