npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

ecpay-guard

v0.1.0

Published

把綠界送來的付款通知,變成可靠、不重複、不遺漏的付款事件:驗簽、去重、模擬付款標記、Next.js / Express handler

Readme

ecpay-guard

把綠界送來的付款通知,變成可靠、不重複、不遺漏的付款事件。

接綠界最難的不是付款按鈕,是付款之後:

  • 買家付完跳回的頁面被關掉了,訂單卻沒開通
  • 同一則通知送來兩次,權限開了兩次、信寄了兩封
  • ATM、超商是「先取號、三天後才付」,程式只會處理信用卡
  • 後台按了「模擬付款」,系統當成真的出貨
  • 處理到一半資料庫掛了,這筆就再也沒人管

ecpay-guard 不是 SDK(建立訂單請用綠界官方 SDK 或其他套件),它只負責收到通知之後這一段。

  • 零執行期依賴,Node 18+,ESM / CommonJS 都可以
  • 檢查碼演算法以綠界文件的官方範例值測試

狀態:v0.1。已在綠界測試環境端到端驗證(2026-10-10):信用卡付款、ATM 取號、超商代碼取號三種通知都正確驗簽、轉成事件並回 1|OK,原始通知收錄為回歸測試。尚未在正式環境收過真錢。

安裝

npm install ecpay-guard

用法(Next.js)

// lib/ecpay.ts
import { createEcpayGuard, postgresStore } from "ecpay-guard";
import { Pool } from "pg";

export const guard = createEcpayGuard({
  merchantId: process.env.ECPAY_MERCHANT_ID!,
  hashKey: process.env.ECPAY_HASH_KEY!,
  hashIV: process.env.ECPAY_HASH_IV!,
  env: "prod", // 測試環境填 "stage"
  store: postgresStore(new Pool()),
  onEvent: async (e) => {
    switch (e.type) {
      case "payment.succeeded":
        await grantAccess(e.orderId); // 請寫成重複執行也沒關係(例如 upsert)
        break;
      case "code.issued":
        await emailPaymentCode(e.orderId, e.code!); // ATM 帳號 / 超商代碼 + 繳費期限
        break;
      case "payment.simulated":
        // 後台模擬付款:買家沒付錢,不要出貨
        break;
    }
  },
});
// app/api/ecpay/notify/route.ts —— ReturnURL 和 PaymentInfoURL 都填這個網址
import { nextHandler } from "ecpay-guard";
import { guard } from "@/lib/ecpay";

export const POST = nextHandler(guard);

Express:

import { expressHandler } from "ecpay-guard";
app.post("/ecpay/notify", expressHandler(guard)); // 有沒有掛 express.urlencoded() 都可以

事件

| type | 什麼時候 | 你該做什麼 | |---|---|---| | payment.succeeded | 付款成功 | 開通、出貨 | | payment.failed | 付款失敗 | 通知買家重試 | | payment.simulated | 正式環境收到後台「模擬付款」 | 不要出貨(綠界不會撥款) | | code.issued | ATM / 超商代碼 / 條碼取號成功 | 把繳費資訊寄給買家;還沒付錢 | | code.failed | 取號失敗 | 請買家換付款方式 |

每個事件都有:orderId(你的 MerchantTradeNo)、tradeNo(綠界交易編號)、amount、method(credit / atm / webatm / cvs / barcode / other)、simulated、customFields、raw(原始參數)。

它幫你處理了什麼

| 狀況 | 處理方式 | |---|---| | 檢查碼不對 | 丟棄,回 0|CheckMacValue Error,記錄 | | 別家特店的通知 | 丟棄 | | 同一則通知送兩次 | 第二次直接回 1|OK,不會再呼叫 onEvent | | 兩台機器同時收到同一則 | 用資料庫原子操作搶處理權,只有一台會處理 | | onEvent 拋錯 | 回非 1|OK,綠界會在 5–15 分鐘後重送(一天最多四次);也可以自己排程 guard.retryUnhandled() | | 處理到一半機器當掉 | 租約(預設 60 秒)過期後,重送或 retryUnhandled() 會接手 | | 後台模擬付款 | 正式環境變成 payment.simulated;測試環境(env: "stage")照常當付款成功,但 simulated: true | | 定期定額通知 | v0.1 還不支援,回 400 並記錄(不會默默吞掉) |

為什麼不能只看跳轉頁:綠界文件明確要求以伺服器通知為準。把付款結果頁(OrderResultURL / ClientBackURL)只當成「顯示用」,開通一律交給 onEvent。

資料庫

postgresStore 接受任何有 query(sql, params) 的物件(node-postgres 的 Pool、PGlite 都可以),不需要額外安裝。

const store = postgresStore(pool);
await store.migrate(); // 或把 postgresSchema() 的 SQL 放進你的 migration

用別的資料庫:實作 Store 介面(src/store.ts,六個方法)。insert 與 claim 必須是原子操作。 memoryStore() 只適合測試:重啟就忘、多台機器不共享。

排程(建議)

// 每 10 分鐘:重跑沒處理成功的事件
await guard.retryUnhandled();

其他工具

import { computeCheckMacValue, verifyCheckMacValue } from "ecpay-guard";

路線

  • v0.2:主動查詢補漏(QueryTradeInfo),處理「通知根本沒送到」;內建限速,避開綠界的 403 / 30 分鐘封鎖
  • v0.3:定期定額(PeriodReturnURL、扣款失敗)
  • 之後:電子發票

授權

MIT