jko-offline-sdk

A Node.js SDK for integrating JKoPay Offline Payment API. 提供街口支付 (JKoPay) 的線下交易 API 封裝，支援付款、退款、取消、查詢等功能。

📦 安裝

npm install jko-offline-sdk dotenv

⚙️ 環境變數設定

在專案根目錄建立 .env 檔：

MERCHANT_KEY=your-merchant-key
SYSTEM_NAME=your-system-name
MERCHANT_ID=your-merchant-id
STORE_ID=your-store-id
STORE_NAME=your-store-name
POS_ID=POS01
BASE_URL=https://pos.jkopay.com

🚀 使用方法

初始化 SDK

require('dotenv').config();
const JKoPaySDK = require('jko-offline-sdk');

const sdk = new JKoPaySDK({
  merchantKey: process.env.MERCHANT_KEY,
  systemName: process.env.SYSTEM_NAME,
  merchantID: process.env.MERCHANT_ID,
  storeID: process.env.STORE_ID,
  storeName: process.env.STORE_NAME,
  posID: process.env.POS_ID,
  baseUrl: process.env.BASE_URL // 可選，預設為官方 API
});

發起付款

(async () => {
  try {
    const result = await sdk.payment({
      cardToken: "test-card-token",
      merchantTradeNo: "ORDER123456",
      tradeAmount: 100,
      remark: "測試交易"
    });
    console.log("付款結果:", result);
  } catch (err) {
    console.error("付款錯誤:", err);
  }
})();

取消交易

await sdk.cancel({
  cardToken: "test-card-token",
  merchantTradeNo: "ORDER123456"
});

退款

await sdk.refund({
  merchantTradeNo: "ORDER123456",
  tradeNo: "JKOTRADE7890",
  tradeAmount: 100
});

查詢交易

const result = await sdk.inquiry({
  merchantTradeNo: "ORDER123456"
});
console.log("查詢結果:", result);

檢查交易狀態

if (sdk.isSuccess(result)) {
  console.log("交易成功");
} else {
  console.log("交易失敗:", sdk.getStatusDescription(result.StatusCode));
}

📖 方法列表

• payment(params) → 發起付款
• cancel(params) → 取消交易
• refund(params) → 退款
• inquiry(params) → 查詢交易
• isSuccess(response) → 判斷交易是否成功
• getStatusDescription(code) → 取得錯誤碼描述

⚠️ 注意事項

• 需先向 街口支付 (JKoPay) 申請 API 使用權限。
• 測試時可使用沙盒環境的 API Key 與參數。
• 請妥善保護 merchantKey，避免洩漏。

📄 授權

ISC © Ming Huan Yang