> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zangsho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 綠界科技

> 串接綠界科技（ECPay）自動接收付款通知，即時建立訂單

## 概覽

帳獸支援與綠界科技（ECPay）整合，自動接收付款通知並建立訂單。設定完成後，當消費者透過綠界科技完成付款，帳獸會自動接收通知、驗證安全性並建立對應的訂單記錄。

## 設定步驟

<Steps>
  <Step title="進入綠界金流設定頁面">
    登入後台，進入 **金流設定** > **綠界金流設定**。
  </Step>

  <Step title="輸入金鑰憑證">
    輸入你在綠界科技後台取得的 API 金鑰：

    | 欄位         | 說明                |
    | ---------- | ----------------- |
    | MerchantID | 商店代號              |
    | HashKey    | 16 字元金鑰，從綠界商店後台取得 |
    | HashIV     | 16 字元金鑰，從綠界商店後台取得 |

    <Tabs>
      <Tab title="正式環境">
        使用綠界科技正式環境的憑證。確認你的綠界帳號已完成商店設定並通過審核。
      </Tab>

      <Tab title="測試環境">
        使用綠界科技測試環境的憑證。測試環境的交易不會產生實際扣款，適合開發階段使用。

        綠界測試環境資訊：

        * MerchantID：`3002607`
        * 測試信用卡號：`4311-9522-2222-2222`
      </Tab>
    </Tabs>
  </Step>

  <Step title="設定 Notify URL">
    系統會自動產生一組專屬的 Notify URL：

    ```
    POST https://app.zangsho.com/webhook/ecpay/{your_merchant_code}
    ```

    將此 URL 設定到你的綠界科技後台的**付款完成通知回傳網址**。

    <Note>
      每個商家都有獨立的 Notify URL，其中 `{your_merchant_code}` 是你的商家代碼。
    </Note>
  </Step>

  <Step title="設定轉發 URL（可選）">
    如果你希望將綠界的付款通知同時轉發到你自己的伺服器，可以設定**轉發 URL**。

    帳獸收到綠界通知後，會將原始資料轉發到你指定的 URL，並附帶以下額外欄位：

    ```json theme={null}
    {
      "_event": "ecpay.notify",
      "_provider": "ecpay",
      "MerchantID": "...",
      "MerchantTradeNo": "...",
      "TradeNo": "...",
      "TradeAmt": 1990,
      "PaymentType": "Credit_CreditCard",
      "TradeDate": "2026/02/09 08:00:00"
    }
    ```

    <Info>
      轉發失敗時，系統會自動重試最多 3 次（間隔 30 秒 → 60 秒 → 120 秒）。
    </Info>
  </Step>

  <Step title="儲存設定">
    點擊**儲存**完成設定。
  </Step>
</Steps>

## 自動訂單建立

綠界科技通知到達後，帳獸會自動：

1. **驗證通知真實性** — 確認通知確實來自綠界科技
2. **建立或更新訂單** — 根據通知內容自動建立訂單記錄（冪等處理，不會重複建立）
3. **對應支付方式** — 自動將綠界的 PaymentType 轉換為帳獸的支付方式

### 支付方式對應

| 綠界 PaymentType     | 帳獸支付方式                 |
| ------------------ | ---------------------- |
| Credit\_CreditCard | 信用卡（`credit_card`）     |
| ATM\_\*            | ATM 轉帳（`atm`）          |
| CVS\_\*            | 超商繳費（`cvs`）            |
| ApplePay           | Apple Pay（`apple_pay`） |

<Note>
  綠界的 ATM 與超商繳費有多種子類型（如 `ATM_TAISHIN`、`CVS_CVS`），帳獸會統一對應到 `atm` 和 `cvs`。
</Note>

### 模擬付款

<Warning>
  當綠界通知中的 `SimulatePaid` 為 `1` 時，表示這是一筆模擬付款，帳獸**不會更新訂單狀態**。模擬付款僅用於測試流程是否正常運作。
</Warning>

## Notify 記錄

你可以在後台查看所有接收到的綠界科技通知記錄：

* **記錄保留期限**：90 天
* **篩選條件**：可依 provider 篩選（`ecpay`）
* **詳情展開**：查看完整通知內容與處理結果

## 常見問題

<AccordionGroup>
  <Accordion title="為什麼帳獸沒有收到綠界的通知？">
    請確認以下事項：

    1. 綠界後台的付款完成通知回傳網址設定正確
    2. 使用 HTTPS 協定
    3. 你的帳獸帳號狀態正常
    4. 綠界的交易確實已完成付款
  </Accordion>

  <Accordion title="同一筆訂單收到多次通知怎麼辦？">
    帳獸會進行冪等處理 — 同一筆訂單編號只會建立一次訂單記錄。重複的通知會被安全忽略。
  </Accordion>

  <Accordion title="測試環境的交易會建立訂單嗎？">
    會。測試環境的交易也會建立訂單記錄（但 `SimulatePaid=1` 的模擬付款不會更新訂單狀態）。你可以稍後刪除測試資料。
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="藍新金流" icon="credit-card" href="/integrations/newebpay">
    設定藍新金流整合。
  </Card>

  <Card title="自動化整合" icon="robot" href="/integrations/automation">
    使用 n8n 或 Make 串接付款通知建立自動化工作流。
  </Card>
</CardGroup>