API Document

1. Overview

node-ecpay-aio (NEA) 是綠界全方位金流(AIO)的 Node.js SDK。NEA 是根據官方 API 規格書的全新實作並且支援 TypeScript，它並非官方 SDK 的 fork 改寫版本。

因綠界主要使用者皆在台灣，故 NEA 文件皆以中文書寫。

安裝

npm install --save node-ecpay-aio

2. 使用流程說說明

          Step 1           |               Step 2               |           Step 3

                                                   +------------+
                             .createPayment()      |            |--> await payment.checkout()
                           +---------------------->|   payment  |
                           |                       |            |--> await payment.placeOrder()
                           |                       +------------+
                           |
                    +------------+                 +------------+
                    |            | .createQuery()  |            |
 new Merchant() --->|  merchant  |---------------->|   query    |--> await query.read()
                    |            |                 |            |
                    +------------+                 +------------+
                           |
                           |                       +------------+
                           |                       |            |
                           +---------------------->|   action   |--> await action.execute()
                             .createAction()       |            |
                                                   +------------+

Step 1: 建立特店（merchant）
Step 2: 可以再用特店建立
- 付款方式: payment
- 查詢: query
- 操作: action
Step 3:
- payment 可以執行結帳
  - 如果是立即付款
    - 一定要在前端導向綠界結帳頁面: await payment.checkout()
  - 如果是延遲付款
    - 可以在前端導向綠界結帳頁面: await payment.checkout()
    - 也可直接於後端請求建立綠界訂單: await payment.placeOrder()
- query 可以執行讀取: await query.read()
- action 可以執行操作: await action.execute()

如何閱讀本文件

建議先稍微讀過官方的 API 手冊。

參數物件會以必填與選填兩部份區隔開。

因參數眾多，僅在需要之處以註解稍加說明。若對某參數不了解，請直接參考官方 API 手冊。

參數命名一律按官方的大寫駝峰式(Pascal Case)書寫。

參數 Schema 或參數間的相依條件已有防衛性驗證，違反規則即會拋錯，故 NEA 文件不會特別說明這些限制。

參數型別是嚴格的，字串就是字串，數字就是數字。官方的 SDK 會自動將字串轉數字，但 NEA 不會，因為這會造成型別混淆。你心裡只要記住幾乎 99% 的參數都是字串，僅有部分涉及「金額」、「次數」、「天數」的地方才會有數字出現。

關於可用參數及其型別、選項，TypeScript 會協助你。不過，到底要用 TS 還是 JS 來寫，由你自行決定。

空值與 undefined 不同。在官方手冊中提到的「空值」在 NEA 中一律是指空字串 '' 而不是 null 或 undefined。本模組中，只要是 undefined 的參數，皆不會編入 x-www-form-urlencoded 的鍵值對字串中。如果你想要將屬性編入 post 字串，請給予該屬性空字串 ''，而非給予 undefined。綠界的請求參數並不使用 null，故請勿使用 null 表示空值。

3. Merchant Class

代表綠界特店的 Class，它的實例帶有工廠方法 createPayment()、createQuery() 以及 createAction() 可以產生特店的結帳、資料查詢與信用卡作業操作。特店是指「提供綠界金流付款服務給消費者付款交易的賣家系統」，一般來講也就是你的後端系統。

import { Merchant } from 'node-ecpay-aio';

3.1 new Merchant()

Syntax:

new Merchant(mode, config[, ecpayServiceUrls])

建立綠界特店的實例。建立時需給予組態 config 用來設定你的特店資訊。Merchant 的實例帶有工廠方法 createPayment()、createQuery() 以及 createAction()。

Arguments:

mode (String): 'Test' | 'Production'，各表示特店要使用綠界的測試環境或生產環境 API。

config (Object): 特店的組態參數如下

{
  // 必填
  MerchantID: '2000132',
  HashKey: '5294y06JbISpM5x9',
  HashIV: 'v77hoKGq4kWxNNIS',
  ReturnURL: 'https://yourservice.com/foo/bar',
  // 選填
  PlatformID: '', // 只有平台商需填此編號, 我們大部分都不是
  PeriodReturnURL: 'https://...',
  OrderResultURL: 'https://...' ,
  ClientBackURL: 'https://...',
  PaymentInfoURL: 'https://...',
  ClientRedirectURL: 'https://...'
}

ecpayServiceUrls (Object, optional): 改寫或新增綠界 API 的服務端點資料，一般不會用到此參數。為節省說明版面，此處暫省略說明。

Returns:

(Object): merchant 實例

Examples:

import { Merchant } from 'node-ecpay-aio';

const merchant = new Merchant('Test', {
  MerchantID: '2000132',
  HashKey: '5294y06JbISpM5x9',
  HashIV: 'v77hoKGq4kWxNNIS',
  ReturnURL: 'https://api.test.com/our/hook1',
  PaymentInfoURL: 'https://api.test.com/our/hook2',
});

3.2 .createPayment()

Syntax:

merchant.createPayment(PaymentClass, baseParams, params);

建立付款方式的工廠方法。建立時請注入要使用的 PaymentClass，並準備好每一種付款方式都要填寫的基本參數 baseParams，以及屬於個別付款方式的專屬參數 params。

注意

建議不要省略 params，即使你並未使用 params 中的任何屬性，請令其為空物件 {} 而非 undefined。

Arguments:

PaymentClass (Class): 各種付款方式的 Class，包含有
- CreditOneTimePayment: 信用卡一次付清
- CreditDividePayment: 信用卡分期付款
- CreditPeriodPayment: 信用卡定期定額 (訂閱式收費)
- WebATMPayment: WebATM 付款
- ATMPayment: ATM 付款
- CVSPayment: 超商代碼付款
- BARCODEPayment: 超商條碼付款
- AndroidPayPayment: Google Pay 付款。綠界目前暫時停止此服務，目前產生 AndroidPayPayment 時會自動 throw Error。

baseParams (Object): 所有付款方式都需要填的基本參數

{
  // 必填
  MerchantTradeNo: 'tn12345678', // 廠商自己的訂單編號, 只接受大小寫英數字組合, min: 4, max: 20
  MerchantTradeDate: '2022/04/25 18:26:12',
  TotalAmount: 500,
  TradeDesc: '交易描述',
  ItemName: '商品名稱',
  // 以下選填
  Remark: '備註',
  NeedExtraPaidInfo: 'Y',        // 'N': 不要, 'Y': 要
  StoreID: '',
  ItemURL: 'https://...',
  CustomField1: '自訂欄位1',
  CustomField2: '自訂欄位2',
  CustomField3: '自訂欄位3',
  CustomField4: '自訂欄位4',
  ReturnURL: 'https://...',      // 若在 merchant 設定過, 此處不需再設定, 除非你針對此單要用個別的 hook
  ClientBackURL: 'https://...',  // 若在 merchant 設定過, 此處不需再設定, 除非你針對此單要用個別的返回網址
  OrderResultURL: 'https://...', // 若在 merchant 設定過, 此處不需再設定, 除非你針對此單要顯示個別的付款結果網址
}

params (Object): 根據不同的 PaymentClass 付款方式，各自需要的獨特參數。分述於下方各種付款方式範例。

Returns:

(Object): payment 實例

Examples:

1. 信用卡一次付清

付款模式: 立即付款（須導向綠界結帳頁）
付款類別: CreditOneTimePayment

  import { Merchant, CreditOneTimePayment } from 'node-ecpay-aio';

  const merchant = new Merchant('Test', { ... }); // ... 略

  const baseParams: BasePaymentParams = {
    MerchantTradeNo: 'tn12345678',
    MerchantTradeDate: '2021/04/17 10:55:26',
    TotalAmount: 1000,
    TradeDesc: '交易描述',
    ItemName: '商品名稱',
    // ReturnURL: undefined,
    // ClientBackURL: undefined,
    // OrderResultURL: undefined,
  };

  const params: CreditOneTimePaymentParams = {
    // 皆為選填
    BindingCard: 1,    // 記憶信用卡: 1 (記) | 0 (不記)
    MerchantMemberID: '2000132u001', // 記憶卡片需加註識別碼: MerchantId+廠商會員編號
    Language: 'ENG',   // 語系: undefined(繁中) | 'ENG' | 'KOR' | 'JPN' | 'CHI'
    Redeem: 'Y',       // 紅利折抵: undefined(不用) | 'Y' (使用)
    UnionPay: 2,       // [需申請]銀聯卡: 0(可用, default) | 1(導至銀聯網) | 2(不可用)
  };

  const payment = merchant.createPayment(CreditOneTimePayment, baseParams, params);
  const htmlRedirectPostForm = await payment.checkout(/* 可選填發票 */);

2. 信用卡分期付款

付款模式: 立即付款（須導向綠界結帳頁）
付款類別: CreditDividePayment

  import { Merchant, CreditDividePayment } from 'node-ecpay-aio';

  const merchant = new Merchant(...);
  const baseParams: BasePaymentParams = { ... };

  const extraParams: CreditDividePaymentParams = {
    // 必填
    CreditInstallment: '3', // 分期數: '3' | '6' | '12' | '18' | '24' | '30N'(圓夢彈性分期)
    // 選填
    BindingCard: 0,
    MerchantMemberID: undefined, // 寫 undefined 只是表示有此參數可設定, 實際上不賦值就不用寫此屬性
    Language: undefined,         // 同上
    Redeem: undefined,           // 同上
    UnionPay: undefined,         // 同上
  };

  const payment = merchant.createPayment(CreditDividePayment, baseParams, params);
  const htmlRedirectPostForm = await payment.checkout(/* 可選填發票 */);

3. 信用卡定期定額

付款模式: 立即付款（須導向綠界結帳頁）
付款類別: CreditPeriodPayment

  import { Merchant, CreditPeriodPayment } from 'node-ecpay-aio';

  const merchant = new Merchant(...);
  const baseParams: BasePaymentParams = { ... };

  const params: CreditPeriodPaymentParams = {
    // 必填
    PeriodAmount: 500, // 週期授權金額, 須與 baseParams.TotalAmount 相等, 否則拋錯
    PeriodType: 'M',   // 'D'(日) | 'M'(月) | 'Y'(年)
    Frequency: 1,      // 多久執行一次, min: 1, max: 365(天) | 12(月) | 1(年)
    ExecTimes: 10,     // 執行次數, min: 1, max: 999(天) | 99(月) | 9(年)
    // 選填
    BindingCard: 0,
    MerchantMemberID: undefined,
    Language: undefined,
    Redeem: undefined,
    UnionPay: 2,
    PeriodReturnURL: 'https://...',  // 若在 merchant 設定過, 此處不需再設定, 除非你針對此單要用個別的 hook
  };

  const payment = merchant.createPayment(CreditPeriodPayment, baseParams, params);
  const htmlRedirectPostForm = await payment.checkout(/* 可選填發票 */);

4. WebATM 付款

付款模式: 立即付款（須導向綠界結帳頁）
付款類別: WebATMPayment

  import { Merchant, WebATMPayment } from 'node-ecpay-aio';

  const merchant = new Merchant(...);
  const baseParams: BasePaymentParams = { ... };

  const params: WebATMPaymentParams = {
    /* 無參數, 請保持空物件*/
  };

  const payment = merchant.createPayment(WebATMPayment, baseParams, params);
  const htmlRedirectPostForm = await payment.checkout(/* 可選填發票 */);

5. ATMPayment 付款

付款模式: 延遲付款（可選擇是否導向綠界結帳頁）
付款類別: ATMPayment

  import { Merchant, ATMPayment } from 'node-ecpay-aio';

  const merchant = new Merchant(...);
  const baseParams: BasePaymentParams = { ... };

  const params: ATMPaymentParams = {
    // 皆選填
    ExpireDate: 7,
    PaymentInfoURL: 'https://...',    // 若在 merchant 設定過, 此處不需再設定, 除非你針對此單要用個別的 hook
    ClientRedirectURL: 'https://...', // 若在 merchant 設定過, 此處不需再設定, 除非你針對此單要用個別的 hook
  };

  const payment = merchant.createPayment(ATMPayment, baseParams, params);

  // pick one
  // (1) 取得前端瀏覽器重新導向的 Post Form
  const htmlRedirectPostForm = await payment.checkout(/* 可選填發票 */);
  // 或 (2) 於後端直接建立訂單, paymentInfo 為取號結果
  const paymentInfo = await payment.placeOrder(/* 可選填發票 */);

6. 超商代碼付款

付款模式: 延遲付款（可選擇是否導向綠界結帳頁）
付款類別: CVSPayment

  import { Merchant, CVSPayment } from 'node-ecpay-aio';

  const merchant = new Merchant(...);
  const baseParams: BasePaymentParams = { ... };

  const params: CVSPaymentParams = {
    // 皆選填
    StoreExpireDate: 7,
    Desc_1: 'POS 機顯示條目 1',
    Desc_2: 'POS 機顯示條目 2',
    Desc_3: 'POS 機顯示條目 3',
    Desc_4: 'POS 機顯示條目 4',
    PaymentInfoURL: 'https://...',    // 若在 merchant 設定過, 此處不需再設定, 除非你針對此單要用個別的 hook
    ClientRedirectURL: 'https://...', // 若在 merchant 設定過, 此處不需再設定, 除非你針對此單要用個別的 hook
  };

  const payment = merchant.createPayment(CVSPayment, baseParams, params);

  // pick one
  // (1) 取得前端瀏覽器重新導向的 Post Form
  const htmlRedirectPostForm = await payment.checkout(/* 可選填發票 */);
  // 或 (2) 於後端直接建立訂單, paymentInfo 為取號結果
  const paymentInfo = await payment.placeOrder(/* 可選填發票 */);

7. 超商條碼付款

付款模式: 延遲付款（可選擇是否導向綠界結帳頁）
付款類別: BARCODEPayment

  import { Merchant, BARCODEPayment } from 'node-ecpay-aio';

  const merchant = new Merchant(...);
  const baseParams: BasePaymentParams = { ... };

  const extraParams: BARCODEPaymentParams = {
    // 皆為可選
    StoreExpireDate: 7,
    PaymentInfoURL: 'https://...',    // 不必特別設定, 因未設定會自動吃 merchant config 的值
    ClientRedirectURL: 'https://...', // 不必特別設定, 因未設定會自動吃 merchant config 的值
    Desc_1: 'POS 機顯示條目 1',
    Desc_2: 'POS 機顯示條目 2',
    Desc_3: 'POS 機顯示條目 3',
    Desc_4: 'POS 機顯示條目 4',
  };

  const payment = merchant.createPayment(BARCODEPayment, baseParams, params);

  // pick one
  // (1) 取得前端瀏覽器重新導向的 Post Form
  const htmlRedirectPostForm = await payment.checkout(/* 可選填發票 */);
  // 或 (2) 於後端直接建立訂單, paymentInfo 為取號結果
  const paymentInfo = await payment.placeOrder(/* 可選填發票 */);

8. Android Pay (GooglePay)

付款模式: 立即付款（AIO 目前已停止本服務）
付款類別: AndroidPayPayment

  import { Merchant, AndroidPayPayment } from 'node-ecpay-aio';

  const merchant = new Merchant(...);
  const baseParams: BasePaymentParams = { ... };

  const params: AndroidPayPaymentParams = {
    /* 綠界當前不提供此服務, 無參數, 請保持空物件 */
  };

  const payment = merchant.createPayment(AndroidPayPayment, baseParams, params);
  const htmlRedirectPostForm = await payment.checkout(/* 可選填發票 */);

9. 使用者自選付款方式

付款模式: 立即付款/延遲付款（須導向綠界結帳頁；不支援 placeOrder()）
付款類別: ALLPayment

  import { Merchant, ALLPayment } from 'node-ecpay-aio';

  const merchant = new Merchant(...);
  const baseParams: BasePaymentParams = { ... };

  const params: ALLPaymentParams = {
    // 選填
    IgnorePayment: ['WebATM', 'ATM'],
    // 陣列可填 'Credit', 'WebATM', 'ATM', 'CVS', 'BARCODE', 'AndroidPay'
    // 表示不提供這些付款方式給消費者選擇

    // 其餘參數: 根據可用的付款方式, 將所有 params 結合起來在此設定
    //          個別設定請參考前述 1~8 之設定
    BindingCard: 0,
    MerchantMemberID: undefined,
    Language: undefined,
    Redeem: undefined,
    UnionPay: 2,
    // ... 略
  };

  const payment = merchant.createPayment(ALLPayment, baseParams, params);
  const htmlRedirectPostForm = await payment.checkout();

3.3 .createQuery()

Syntax:

merchant.createQuery(QueryClass, params);

建立交易資料查詢的工廠方法。建立時請注入要使用的 QueryClass，並準備好每一種查詢要填寫的參數 params。建立的 QueryClass 實例具有 .read() 的非同步方法可以向綠界服務發起查詢請求。查詢結果的響應格式請見 Query Class: 5.1 .read() API 說明。Query 是冪等操作。

注意

建議不要省略 params，即使你並未使用 params 中的任何屬性，請令其為空物件 {} 而非 undefined。

Arguments:

QueryClass (Class): 各種查詢的 Class，包含有
- TradeInfoQuery: 訂單資料查詢
- PaymentInfoQuery: ATM/CVS/BARCODE 取號結果查詢
- CreditCardPeriodInfoQuery: 信用卡定期定額訂單查詢
- TradeV2Query: 查詢信用卡單筆明細紀錄
- TradeNoAioQuery: 下載特店對帳媒體檔
- FundingReconDetail: 下載信用卡撥款對帳資料檔
params (Object): 根據不同的 QueryClass 查詢方式，各自所需的獨特參數。分述於下方各種查詢範例。

Returns:

(Object): query 實例

Examples:

1. 查詢訂單資料

查詢類別: TradeInfoQuery

  import { Merchant, TradeInfoQuery } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(TradeInfoQuery, {
    MerchantTradeNo: 'tn12345678'
  });

  const data = await query.read();

2. 查詢延遲付款取號結果

查詢類別: PaymentInfoQuery

  import { Merchant, PaymentInfoQuery } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(PaymentInfoQuery, {
    MerchantTradeNo: 'tn12345678'
  });

  const data = await query.read();

3. 查詢信用卡定期定額訂單

查詢類別: CreditCardPeriodInfoQuery

  import { Merchant, CreditCardPeriodInfoQuery } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(CreditCardPeriodInfoQuery, {
    MerchantTradeNo: 'tn12345678'
  });

  const data = await query.read();

4. 查詢信用卡單筆明細紀錄

查詢類別: TradeV2Query

  import { Merchant, TradeV2Query } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(TradeV2Query, {
    CreditRefundId: 10123456,  // baseParams.NeedExtraPaidInfo = 'Y' 時取得詳情中的 gwsr 值即是此 Id
    CreditAmount: 500,
    CreditCheckCode: 59997889  // 商家檢查碼, 後台 > 信用卡收單 > 信用卡授權資訊可查到
  });

  const data = await query.read();

5. 下載特店對帳媒體檔

查詢類別: TradeNoAioQuery

  import { Merchant, TradeNoAioQuery } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(TradeNoAioQuery, {
    // 必填
    DateType: '2', // '2'(付款日) | '4'(撥款日) | '6'(訂單日)
    BeginDate: '2022-04-25',
    EndDate: '2022-04-26',
    MediaFormated: '1', // '0'(舊格式) | '1'(新格式)
    // 選填
    PaymentType: '01', // '01'(信用卡) | '02'(WebATM) | '03'(ATM) | '04'(CVS) | '05'(BARCODE) | '10'(全家立即儲) | '11'(圓夢彈性分期);
    PlatformStatus: undefined, // undefined(全部) | '1'(一般) | '2'(平台)
    PaymentStatus: '0', // undefined(全部) | '0'(未付款) | '1'(已付款) | '2'(訂單失敗)
    AllocateStatus: undefined, //  undefined(全部) | '0'(未撥款) | '1'(已撥款)
    CharSet: '1', // undefeind(Server預設) | '1'(Big5) | '2'(utf8);
  });

  const data: string = await query.read();  // csv檔

response data: 純文字 (.csv 檔)

6. 下載信用卡撥款對帳資料檔

查詢類別: FundingReconDetail

  import { Merchant, FundingReconDetail } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(FundingReconDetail, {
    // 必填
    PayDateType: 'fund', // 'fund'(依結算日) | 'close'(依關帳日) | 'enter'(依撥款日)
    StartDate: '2022-04-25',
    EndDate: '2022-04-26',
    MediaFormated: '1', // '0'(舊格式) | '1'(新格式)
    // 選填
    CharSet: '1', // undefeind(Server預設) | '1'(Big5) | '2'(utf8);
  });

  const data: string = await query.read(); // csv檔

response data: 純文字 (.csv 檔)

3.4 .createAction()

Syntax:

merchant.createAction(ActionClass, params);

建立操作的工廠方法。建立時請注入要使用的 ActionClass，並準備好每一種操作要填寫的參數 params。建立的 ActionClass 實例具有 .execute() 的非同步方法可以向綠界服務發起遠端操作請求。操作結果的響應格式請見 Action Class: 6.1 .execute() API 說明。Action 是非冪等操作。

注意

建議不要省略 params，即使你並未使用 params 中的任何屬性，請令其為空物件 {} 而非 undefined。

Arguments:

ActionClass (Class): 各種操作的 Class，包含有
- DoAction: 信用卡請退款作業
- CreditCardPeriodAction: 信用卡定期定額訂單作業
params (Object): 根據不同的 ActionClass 操作方式，各自所需的獨特參數。分述於下方各種操作範例。

Returns:

(Object): action 實例

Examples:

1. 信用卡關帳、請退款

操作類別: DoAction

  const action = merchant.createAction(DoAction, {
    // 皆為必填
    MerchantTradeNo: 'tn12345678',
    TradeNo: '8811223388121'.
    Action: 'C' , // 'C'(關帳) | 'R'(退刷) | 'E'(取消) | 'N'(放棄)
    TotalAmount: 500
  });

  const result = await action.execute(); // {}

response data

{
  MerchantID: '2000132',
  MerchantTradeNo: '20211026001969730',
  TradeNo: '20120315174058256423',
  RtnCode: 1,
  RtnMsg: '關帳成功',
}

2. 信用卡定期定額訂單作業

操作類別: CreditCardPeriodAction

const action = merchant.createAction(CreditCardPeriodAction, {
  // 皆為必填
  MerchantTradeNo: 'tn12345678',
  Action: 'ReAuth', // 'ReAuth' | 'Cancel';
});

const result = await action.execute(); // {}

response data

{
  CheckMacValue: '205B4135AAB1F78AAD407838E344A291C0CCD67BB3188A58992B07F27BE61006',
  MerchantID: '2000132',
  MerchantTradeNo: '20211026001969730',
  RtnCode: 1,
  RtnMsg: '停用成功',
}

4. Payment Class

Payment Classes 分類如下:

立即付款類
- CreditOneTimePayment: 信用卡一次付清
- CreditDividePayment: 信用卡分期付款
- CreditPeriodPayment: 信用卡定期定額 (訂閱式收費)
- AndroidPayPaymen: Google Pay 付款。綠界目前暫時停止此服務，目前產生 AndroidPayPayment 時會自動 throw Error。
延遲付款類
- WebATMPayment: WebATM 付款
- ATMPayment: ATM 付款
- CVSPayment: 超商代碼付款
- BARCODEPayment: 超商條碼付款

4.1 .checkout()

Syntax:

payment.checkout([invoice]);

所有的 Payment Classes 都有 .checkout() 的結帳方法。如果需要開立電子發票，請於結帳時帶入發票參數 chekcout(invoice)。如不開立發票，直接執行checkout()即可。

Arguments:

invoice (Object, optional): 發票參數結帳時開立電子發票

Returns:

(String): html redirect post form

Examples:

1. 不開立電子發票

const htmlRedirectPostForm = await payment.checkout();

result (a html redirect post form)

<form
  id="_form_aio_checkout"
  action="https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5"
  method="post"
>
  <input
    type="hidden"
    name="CheckMacValue"
    id="CheckMacValue"
    value="2C6E582088B63CE828D27CE7E89FE0BA840F2599F10002A6AC0213DFD147C116"
  />...略...<input
    type="hidden"
    name="TradeDesc"
    id="TradeDesc"
    value="node-ecpay-aio testing order for CreditOneTimePayment"
  />
  <script type="text/javascript">
    document.getElementById('_form_aio_checkout').submit();
  </script>
</form>

2. 要開立電子發票

const invoice: InvoiceParams = {
  RelateNumber: 'rl-no',
  TaxType: '1',
  Donation: '0',
  Print: '0',
  InvoiceItemName: 'item1|item2',
  InvoiceItemCount: '2|5',
  InvoiceItemWord: '台|張',
  InvoiceItemPrice: '100|50',
  InvoiceRemark: '測試發票備註',
  CustomerPhone: '0911111111',
};

const htmlRedirectPostForm = await payment.checkout(invoice);

result (a html redirect post form)

<form
  id="_form_aio_checkout"
  action="https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5"
  method="post"
>
  <input type="hidden" name="CarruerType" id="CarruerType" value="" /><input
    type="hidden"
    name="CheckMacValue"
    id="CheckMacValue"
    value="3185EDD19B600CA2780AD3DE387DB09434A84AE0BE37B64EB36C428D3BA40264"
  />...略...<input
    type="hidden"
    name="TotalAmount"
    id="TotalAmount"
    value="999"
  /><input
    type="hidden"
    name="TradeDesc"
    id="TradeDesc"
    value="node-ecpay-aio testing order for CreditOneTimePayment"
  />
  <script type="text/javascript">
    document.getElementById('_form_aio_checkout').submit();
  </script>
</form>

4.2 .placeOrder()

Syntax:

payment.placeOrder([invoice]);

只有延遲付款的 Payment Classes 才有 .placeOrder() 方法。如果需要開立電子發票，請於結帳時帶入發票參數placeOrder(invoice)。如不開立發票，直接執行placeOrder()即可。

Arguments:

invoice (Object, optional): 發票參數結帳時開立電子發票

Returns:

(Object): 取號結果

Examples:

1. 不開立電子發票

const info = await payment.placeOrder();

2. 開立電子發票

const info = await payment.placeOrder({
  ...
});

5. Query Class

5.1 .read()

Syntax:

query.read();

所有的 Query Classes 都有 .read() 的查詢資料讀取方法。

Arguments:

invoice (Object, optional): 發票參數結帳時開立電子發票

Returns:

(Promise): promise

Examples:

1. 查詢訂單

  import { Merchant, TradeInfoQuery } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(TradeInfoQuery, {
    MerchantTradeNo: 'tn12345678'
  });

  const data = await query.read(); // 響應格式列如下方

響應資料

(1) 信用卡一次付清與分期

{
    CheckMacValue: 'ABCD...',
    MerchantID: '2000132',
    StoreID: '',
    MerchantTradeNo: '4e5c882cab5a4796be7f',
    ItemName: '手機/平板 鋁合金桌面支架 | 人體工 學追劇必備#',
    CustomField1: '',
    CustomField2: '',
    CustomField3: '',
    CustomField4: '',
    TradeNo: '2204261428508660',
    TradeDate: '2022/04/26 14:28:50',
    TradeAmt: 1440,
    TradeStatus: '1',
    HandlingCharge: 29,
    PaymentDate: '2022/04/26 14:29:15',
    PaymentType: 'Credit_CreditCard',
    PaymentTypeChargeFee: 29,
    // 以下欄位只有當結帳時 baseParams.NeedExtraPaidInfo 設 'Y' 才有
    // 故不一定會在響應資料中出現
    // 以下欄位和信用卡交易方式有關
    process_date: '2022/04/27 17:19:44',
    amount: 1440,
    auth_code: '777777',
    gwsr: 11718189,
    eci: 0,
    card4no: '2222',
    card6no: '431195',
    // 以下欄位和此交易方式無關
    ATMAccBank: '',
    ATMAccNo: '',
    WebATMBankName: '',
    WebATMAccBank: '',
    WebATMAccNo: '',
    PayFrom: '',
    PaymentNo: '',
    red_dan: '',
    red_de_amt: '',
    red_ok_amt: '',
    red_yet: '',
    staed: '',
    stage: '',
    stast: '',
    // 以下官方已棄用
    AlipayID: '',
    AlipayTradeNo: '',
    TenpayTradeNo: '',
}

(2) 信用卡定期定額訂單

 {
   CheckMacValue: 'ABCD...',
   MerchantID: '2000132',
   StoreID: '',
   MerchantTradeNo: '20211026001969730',
   ItemName: 'test       200 新台幣 x 1',
   CustomField1: '',
   CustomField2: '',
   CustomField3: '',
   CustomField4: '',
   TradeNo: '2110261713558708',
   TradeDate: '2021/10/26 17:13:55',
   TradeAmt: 200,
   TradeStatus: '1',
   HandlingCharge: 5,
   PaymentDate: '2021/10/26 17:14:27',
   PaymentType: 'Credit_CreditCard',
   PaymentTypeChargeFee: 5,
   PeriodType: 'D',
   Frequency: 91,
   ExecTimes: 999,
   TotalSuccessTimes: 3,
   PeriodAmount: 200,
   TotalSuccessAmount: 600,
   // 以下欄位和信用卡交易方式有關
   process_date: '2021/10/26 17:14:27',
   amount: 200,
   auth_code: '777777',
   gwsr: 11718189,
   card4no: '2222',
   card6no: '431195',
   eci: '',  // 當非數字時，保持空值(空字串)
   // 其餘欄位和此交易方式無關, 也不一定會出現
   // 所有欄位請參考上方完整的 response data 格式
   // ...略
 }

(3) WebATM 訂單

{

   CheckMacValue: 'ABCD...',
   MerchantID: '2000132',
   StoreID: '',
   MerchantTradeNo: '20220426133333',
   ItemName: '湊町十六－打go嚴選-【黑水】雙鬥茶 200 元 x 2#運費 137 元 x 1',
   CustomField1: '商家統一編號：83269087',
   CustomField2: '',
   CustomField3: '',
   CustomField4: '',
   TradeNo: '2204261333378539',
   TradeDate: '2022/04/26 13:33:37',
   TradeAmt: '537',
   TradeStatus: '1',
   HandlingCharge: '10',
   PaymentDate: '2022/04/26 13:33:45',
   PaymentType: 'WebATM_TAISHIN',
   PaymentTypeChargeFee: '10',
   WebATMBankName: '',
   WebATMAccBank: '812',
   WebATMAccNo: '15646',
   // 其餘欄位和此交易方式無關, 也不一定會出現
   // 所有欄位請參考上方完整的 response data 格式
   // ...略
}

(4) ATM 訂單

{
   CheckMacValue: 'ABCD...',
   MerchantID: '2000132',
   StoreID: '',
   MerchantTradeNo: 'N22042600020513',
   ItemName:
     '日本金鳥-吊掛式蚊香盤一般尺寸 173 元 X1#雙龍牌 日式兒童前開式雨衣-XS/S/M/L 136 元 X1',
   CustomField1: '',
   CustomField2: '',
   CustomField3: 'N22042600020',
   CustomField4: 'ATM',
   TradeNo: '2204261421418645',
   TradeDate: '2022/04/26 14:21:41',
   TradeAmt: 409,
   TradeStatus: '0',
   HandlingCharge: '10',
   PaymentDate: '',
   PaymentType: 'ATM_LAND',
   PaymentTypeChargeFee: 10,
   ATMAccBank: '',
   ATMAccNo: '',
   // 其餘欄位和此交易方式無關, 也不一定會出現
   // 所有欄位請參考上方完整的 response data 格式
   // ...略
}

(5) 超商代碼訂單

{
   CheckMacValue: 'ABCD...',
   MerchantID: '2000132',
   StoreID: '',
   MerchantTradeNo: '2204220310222',
   ItemName: '顥陽蘭坊 5000 TWD x 1',
   CustomField1: '',
   CustomField2: '',
   CustomField3: '',
   CustomField4: '',
   TradeNo: '2204261439048696',
   TradeDate: '2022/04/26 14:39:04',
   TradeAmt: 200,
   TradeStatus: '1',
   HandlingCharge: '0',
   PaymentNo: 'LLL22112732600',
   PaymentDate: '2022/04/22 14:11:30',
   PaymentType: 'CVS_CVS',
   PayFrom: 'ibon',
   PaymentTypeChargeFee: 0,
   // 其餘欄位和此交易方式無關, 也不一定會出現
   // 所有欄位請參考上方完整的 response data 格式
   // ...略
}

(6) 超商條碼訂單

{
   CheckMacValue: 'ABCD...',
   MerchantID: '2000132',
   StoreID: '',
   MerchantTradeNo: '2204220310222',
   ItemName: '顥陽蘭坊 5000 TWD x 1',
   CustomField1: '',
   CustomField2: '',
   CustomField3: '',
   CustomField4: '',
   TradeNo: '2204261439048696',
   TradeDate: '2022/04/26 14:39:04',
   TradeAmt: 200,
   TradeStatus: '1',
   HandlingCharge: 0,
   PaymentNo: 'LLL22112732600',
   PaymentDate: '2022/04/22 14:11:30',
   PaymentType: 'BARCODE_BARCODE',
   PayFrom: 'family',
   PaymentTypeChargeFee: 0,
   // 其餘欄位和此交易方式無關, 也不一定會出現
   // 所有欄位請參考上方完整的 response data 格式
   // ...略
}

2. 查詢延遲付款取號結果

  import { Merchant, PaymentInfoQuery } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(PaymentInfoQuery, {
    MerchantTradeNo: 'tn12345678'
  });

  const data = await query.read();

響應資料

(1) ATM

  {
     CheckMacValue: 'ABCD...',
     MerchantID: '2000132',
     StoreID: '',
     MerchantTradeNo: 'N22042600020513',
     CustomField1: '',
     CustomField2: '',
     CustomField3: 'N22042600020',
     CustomField4: 'ATM',
     TradeNo: '2204261421418645',
     TradeDate: '2022/04/26 14:21:51',
     TradeAmt: 409,
     PaymentType: 'ATM_LAND',
     ExpireDate: '2022/04/29',
     BankCode: '005',
     vAccount: '5219111913209840',
     RtnCode: 2,
     RtnMsg: 'Get VirtualAccount Succeeded',
  }

(2) 超商代碼

  {
     CheckMacValue: 'ABCD...',
     MerchantID: '2000132',
     StoreID: '',
     MerchantTradeNo: '7c80cdef716c4a2998d',
     CustomField1: '',
     CustomField2: '',
     CustomField3: '',
     CustomField4: '',
     TradeNo: '2204261439048696',
     TradeDate: '2022/04/26 14:39:30',
     TradeAmt: 200,
     PaymentType: 'CVS_CVS',
     ExpireDate: '2022/05/03 14:39:30',
     PaymentNo: 'LLL22116735498',
     PaymentURL:
       'https://payment-stage.ecpay.com.tw/PaymentRule/CVSBarCode?PaymentNo=LLL22116735498',
     RtnCode: 10100073,
     RtnMsg: 'Get CVS Code Succeeded.',
  }

(3) 超商條碼

  {
     CheckMacValue: 'ABCD...',
     MerchantID: '2000132',
     StoreID: '',
     MerchantTradeNo: 'CK20220426401292',
     CustomField1: '',
     CustomField2: '',
     CustomField3: '',
     CustomField4: '',
     TradeNo: '2204261401048597',
     TradeDate: '2022/04/26 14:02:17',
     TradeAmt: 1500,
     PaymentType: 'BARCODE_BARCODE',
     ExpireDate: '2022/05/03 14:39:30',
     Barcode1: '1105036EA',
     Barcode2: '3453011539919569',
     Barcode3: '042677000001500',
     RtnCode: 10100073,
     RtnMsg: 'Get CVS Code Succeeded.',
  }

(4) 無法查詢者

無法查詢「信用卡」、「ATM」立即付款的資訊（PaymentInfoQuery 只適用查詢延遲付款訂單)

  {
     // ... 略
     RtnCode: 10200047,
     RtnMsg: 'Cant not find the trade data.',
  }

3. 查詢信用卡定期定額訂單

  import { Merchant, CreditCardPeriodInfoQuery } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(CreditCardPeriodInfoQuery, {
    MerchantTradeNo: 'tn12345678'
  });

  const data = await query.read();

響應資料

(1) 信用卡定期定額

  {
    MerchantID: '2000132',
    MerchantTradeNo: 'a2394da5fa5c4ef6b0b',
    TradeNo: '2204260959138173',
    PeriodType: 'M',
    Frequency: 1,
    ExecTimes: 12,
    TotalSuccessTimes: 1,
    PeriodAmount: 100,
    TotalSuccessAmount: 100,
    RtnCode: 1,
    ExecStatus: '1',
    ExecLog: [
      {
        RtnCode: 1,
        RtnMsg: '成功.',
        TradeNo: '2204260959138173',
        amount: 100,
        auth_code: '777777',
        gwsr: 11955800,
        process_date: '2022/04/26 10:00:22',
      },
    ],
    process_date: '2022/04/26 10:00:22',
    amount: 100,
    auth_code: '777777',
    gwsr: 11955800,
    card4no: '4444',
    card6no: '431195',
  }

(2) 無法查詢者

無法查詢信用卡「一次付清」、「分期」付款資訊

  {
    MerchantID: '0',
    MerchantTradeNo: null,
    RtnCode: 10200047,
    // ... 略
  }

4. 查詢信用卡單筆明細紀錄

  import { Merchant, TradeV2Query } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(TradeV2Query, {
    CreditRefundId: 10123456,  // baseParams.NeedExtraPaidInfo = 'Y' 時取得詳情中的 gwsr 值即是此 Id
    CreditAmount: 500,
    CreditCheckCode: 59997889  // 商家檢查碼, 後台 > 信用卡收單 > 信用卡授權資訊可查到
  });

  const data = await query.read();

響應資料

{
  RtnMsg: "",
  RtnValue: {
    TradeID: '0015625112',
    amount: 100,
    clsamt: 100,
    authtime: "2016/5/12 下午 07:09:17",
    status: "已關帳"
    close_data: [
      {
         status: "已關帳",
         sno: "2782343",
         amount: 100,
         datetime: "2016/5/12 下午 08:00:00"
      }
    ]
  },
}

5. 下載特店對帳媒體檔

  import { Merchant, TradeNoAioQuery } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(TradeNoAioQuery, {
    // 必填
    DateType: '2', // '2'(付款日) | '4'(撥款日) | '6'(訂單日)
    BeginDate: '2022-04-25',
    EndDate: '2022-04-26',
    MediaFormated: '1', // '0'(舊格式) | '1'(新格式)
    // 選填
    PaymentType: '01', // '01'(信用卡) | '02'(WebATM) | '03'(ATM) | '04'(CVS) | '05'(BARCODE) | '10'(全家立即儲) | '11'(圓夢彈性分期);
    PlatformStatus: undefined, // undefined(全部) | '1'(一般) | '2'(平台)
    PaymentStatus: '0', // undefined(全部) | '0'(未付款) | '1'(已付款) | '2'(訂單失敗)
    AllocateStatus: undefined, //  undefined(全部) | '0'(未撥款) | '1'(已撥款)
    CharSet: '1', // undefeind(Server預設) | '1'(Big5) | '2'(utf8);
  });

  const data: string = await query.read();  // csv檔

響應資料

純文字 (.csv 檔)

6. 下載信用卡撥款對帳資料檔

  import { Merchant, FundingReconDetail } from 'node-ecpay-aio';

  const merchant = new Merchant(...);

  const query = merchant.createQuery(FundingReconDetail, {
    // 必填
    PayDateType: 'fund', // 'fund'(依結算日) | 'close'(依關帳日) | 'enter'(依撥款日)
    StartDate: '2022-04-25',
    EndDate: '2022-04-26',
    MediaFormated: '1', // '0'(舊格式) | '1'(新格式)
    // 選填
    CharSet: '1', // undefeind(Server預設) | '1'(Big5) | '2'(utf8);
  });

  const data: string = await query.read(); // csv檔

響應資料

純文字 (.csv 檔)

6. Action Class

6.1 .execute()

Syntax:

action.execute();

所有的 Action Classes 都有 .execute() 的執行操作方法。

Arguments:

none

Returns:

(Promise): promise

Examples:

const reuslt = action.execute();

各種不同操作的回傳結果資料請參考 createAction() API 說明。

7. 範例

import { Merchant } from 'node-ecpay-aio';

// Step 1: 建立特店
const merchant = new Merchant('Test', { // 生產環境請記得將 'Test' 改成 'Production'
  MerchantID: 'your-merchant-id',
  HashKey: 'your-merchant-hashkey',
  HashIV: 'your-merchant-hashiv',
  ReturnURL: 'https://api.test.com/your/hook',
});

// [使用情境一] Step 2: 特店建立 payment => Step 3: 結帳

const payment = merchant.createPayment(CreditOneTimePayment, {});
const htmlRedirectPostForm = await payment.checkout({
  // 結帳時給予發票資訊即表示要開立發票
  RelateNumber: 'order-123456',
  TaxType: '1',
  Donation: '0',
  Print: '0',
  InvoiceItemName: '鉛筆|橡皮擦',
  InvoiceItemCount: '10|2',
  InvoiceItemWord: '支|顆',
  InvoiceItemPrice: '12|18',
  DelayDay: 0,
});

// [使用情境二] Step 2: 特店建立 query => Step 3: 執行查詢

const tradeInfoQuery = merchant.createQuery(TradeInfoQuery, {
  MerchantTradeNo: 'tn12345678',
});

const tradeInfo = await tradeInfoQuery.read();

// [使用情境三] Step 2: 特店建立 action => Step 3: 執行操作

const reAuthAction = merchant.createAction(CreditCardPeriodAction, {
   MerchantTradeNo: 'some-trade-no';
   Action: 'ReAuth'
});

const reAuthResult = await reAuthAction.execute();

API Document

1. Overview

安裝

2. 使用流程說說明

3. Merchant Class

3.1 new Merchant()

3.2 .createPayment()

1. 信用卡一次付清

2. 信用卡分期付款

3. 信用卡定期定額

4. WebATM 付款

5. ATMPayment 付款

6. 超商代碼付款

7. 超商條碼付款

8. Android Pay (GooglePay)

9. 使用者自選付款方式

3.3 .createQuery()

1. 查詢訂單資料

2. 查詢延遲付款取號結果

3. 查詢信用卡定期定額訂單

4. 查詢信用卡單筆明細紀錄

5. 下載特店對帳媒體檔

6. 下載信用卡撥款對帳資料檔

3.4 .createAction()

1. 信用卡關帳、請退款

2. 信用卡定期定額訂單作業

4. Payment Class

4.1 .checkout()

1. 不開立電子發票

2. 要開立電子發票

4.2 .placeOrder()

1. 不開立電子發票

2. 開立電子發票

5. Query Class

5.1 .read()

1. 查詢訂單

響應資料

(1) 信用卡一次付清與分期

(2) 信用卡定期定額訂單

(3) WebATM 訂單

(4) ATM 訂單

(5) 超商代碼訂單

(6) 超商條碼訂單

2. 查詢延遲付款取號結果

響應資料

(1) ATM

(2) 超商代碼

(3) 超商條碼

(4) 無法查詢者

3. 查詢信用卡定期定額訂單

響應資料

(1) 信用卡定期定額

(2) 無法查詢者

4. 查詢信用卡單筆明細紀錄

響應資料

5. 下載特店對帳媒體檔

響應資料

6. 下載信用卡撥款對帳資料檔

響應資料

6. Action Class

6.1 .execute()

7. 範例

Uh oh!

Uh oh!

Clone this wiki locally