Bayarlah API Wrapper

A TypeScript REST API wrapper for Bayarlah's terminal and payment endpoints. It handles request signing and gives you a typed client instead of hand-rolling axios calls.

All API based on Bayarlah API doc at https://doc.bayarlah.my

Installation

npm install bayarlah

Quick start

import { BayarlahClient } from "bayarlah";

const bayarlah = new BayarlahClient({
  baseUrl: "https://api.bayarlah.net", // optional, has a default
  timeoutMs: 10_000,                           // optional, defaults to 10s
});

const result = await bayarlah.CheckIn({
  terminal_sn: "TERMINAL-SN",
  terminal_key: "TERMINAL-KEY",
  device_id: "DEVICE-ID",
  os_info: "Android 14",
});

if (result.status === "OK") {
  console.log(result.data);
} else {
  console.error(result.data); // signing/validation failure message
}

Every method returns a BayarlahResponse:

interface BayarlahResponse {
  status: "OK" | "NO";
  data: any;
}

• status: "OK" — the request was signed and sent; data is the API's response body.
• status: "NO" — the request couldn't be signed (e.g. missing sn/key); data holds the failure message and no network call was made.

Network/HTTP-level failures (timeouts, non-2xx responses, etc.) are thrown as a BayarlahApiError instead — wrap calls in try/catch if you want to handle those separately from the "NO" status case.

import { BayarlahApiError } from "bayarlah";

try {
  await bayarlah.CreateQR({ /* ... */ });
} catch (err) {
  if (err instanceof BayarlahApiError) {
    console.error(err.status, err.data);
  }
}

Methods

All methods are async and take a single options object.

Method	Endpoint	Auth
Activate(opts)	POST /terminal/activate	vendor_sn + vendor_key
CheckIn(opts)	POST /terminal/checkin	terminal_sn + terminal_key
CreateQR(opts)	POST /upay/v2/precreate	terminal_sn + terminal_key
ScanCustomerQR(opts)	POST /upay/v2/pay	terminal_sn + terminal_key
QueryTransaction(opts)	POST /upay/v2/query	terminal_sn + terminal_key
RefundTransaction(opts)	POST /upay/v2/refund	terminal_sn + terminal_key
CancelTransaction(opts)	POST /upay/v2/cancel	terminal_sn + terminal_key

Activate

Activates a terminal using vendor credentials; typically run once to obtain a terminal_sn/terminal_key pair for subsequent calls.

Do Activate only only once. Bears repeating, only ONCE. The first time.

await bayarlah.Activate({
  app_id: "APP-ID",
  activation_code: "ACTIVATION-CODE",
  device_id: "DEVICE-ID",
  client_sn: "CLIENT-SN",
  name: "Terminal name",
  os_info: "Android 14",
  vendor_sn: "VENDOR-SN",
  vendor_key: "VENDOR-KEY",
});

CheckIn

await bayarlah.CheckIn({
  terminal_sn: "TERMINAL-SN",
  terminal_key: "TERMINAL-KEY",
  device_id: "DEVICE-ID",
  os_info: "Android 14",
});

CreateQR

Generates a merchant-presented QR code for a customer to scan.

await bayarlah.CreateQR({
  terminal_sn: "TERMINAL-SN",
  terminal_key: "TERMINAL-KEY",
  client_sn: "CLIENT-SN",
  total_amount: "100", //Total amount RM 1.00
  payway: "WECHAT",
  subject: "Order #123",
  operator: "cashier1",
});

ScanCustomerQR

Charges a customer-presented QR code (dynamic_id) that the terminal scanned.

await bayarlah.ScanCustomerQR({
  terminal_sn: "TERMINAL-SN",
  terminal_key: "TERMINAL-KEY",
  client_sn: "CLIENT-SN",
  total_amount: "100", //Total amount RM 1.00
  dynamic_id: "SCANNED-QR-CODE",
  subject: "Order #123",
  operator: "cashier1",
});

QueryTransaction

await bayarlah.QueryTransaction({
  terminal_sn: "TERMINAL-SN",
  terminal_key: "TERMINAL-KEY",
  client_sn: "CLIENT-SN",
});

RefundTransaction

await bayarlah.RefundTransaction({
  terminal_sn: "TERMINAL-SN",
  terminal_key: "TERMINAL-KEY",
  client_sn: "CLIENT-SN",
  refund_request_no: "REFUND-REQUEST-NO",
  refund_amount: "100", //Refund RM 1.00
  operator: "cashier1",
});

CancelTransaction

await bayarlah.CancelTransaction({
  terminal_sn: "TERMINAL-SN",
  terminal_key: "TERMINAL-KEY",
  client_sn: "CLIENT-SN",
});

License

MIT