Skip to content

simenkid/node-ecpay-aio

Repository files navigation

node-ecpay-aio

A production-ready 綠界全方位金流(ECPay All-In-One, AIO) SDK for Node.js with TypeScript Support

build Coverage Badge npm npm node version TypeScript


Documentation

本模組詳細使用說明請見 User Guide


Overview

本模組是根據綠界官方 AIO 規格的全新實作,並非官方維護的 SDK 或是 fork 改寫版本。此模組的設計初衷是為了與官方最新的 API 規格一致、更貼近 JS 開發風格、提供 TypeScript 支援、盡可能完善的自動化測試以及更完善的文件說明。


對應官方版本


Installation

npm install --save node-ecpay-aio

Features

  • 內建 TypeScript 支援
  • 按職責區分 Merchant (特店)、Payment (付款方式)、Query (查詢)、Action (操作)等類別
  • ATM、超商代碼與超商條碼可於後端建立訂單時一併獲得取號結果
  • 結構化的錯誤訊息,更易於程式流程控制
  • 使用 yup 對 API 要求參數與相依條件進行防衛驗證
  • 自動為 REQ/RSP 產生與驗證 CheckMacValue,若驗證到接收響應之校驗碼不符會自動拋錯
  • 遠端查詢或操作作業失敗,會自動拋錯並附帶綠界傳回的錯誤碼、錯誤訊息與原始響應資料
  • 自動設定 derivable 的參數,如 ChoosePayment, InvoiceMark
  • 支援 Node.js v10.x 以上 (自動測試環境包含 v10.x, v12.x, v14.x 與 v16.x)
  • Serverless (Lambda) friendly

Notes

  • 使用前建議先讀過官方文件與本模組 User Guide
  • 歡迎發 Issue,但我不一定有時間修
  • 更歡迎發 PR(帶測試佳)或共同維護
  • 本模組基本穩定,但有些功能綠界沒有提供 Testing stage,自動化測試跑不到那些 cases。

Updates

  • v0.2.2 (2022/09/29)
    • OrderResultURL, ClientBackURL, ClientRedirectURL 三個參數的驗證從必為 URL 改為不一定要為 URL,因在手機使用的情況可能會使用 deep link 重導。故現在開發者要自行保證 OrderResultURL, ClientBackURL, ClientRedirectURL 三個參數的格式。
  • v0.2.3 (2022/09/30)
    • 對 URL 的驗證改為符合 IETF RFC3986 的格式 - ReturnURL, PeriodReturnURL, PaymentInfoURL 可以接受 http://localhost - v0.2.3 起的驗證不會保證你是否使用 https 開頭的網址,故生產時,請開發者要自行保證網址的合法性

License

Licensed under MIT.