> ## 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.

# 藍新金流

> 串接藍新金流（Newebpay）自動接收付款通知，即時建立訂單

## 概覽

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

## 設定步驟

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

  <Step title="輸入金鑰憑證">
    輸入你在藍新金流後台取得的 API 金鑰：

    | 欄位      | 說明                |
    | ------- | ----------------- |
    | HashKey | 32 字元金鑰，從藍新商店後台取得 |
    | HashIV  | 16 字元金鑰，從藍新商店後台取得 |

    <Tabs>
      <Tab title="正式環境">
        使用藍新金流正式環境的 HashKey 與 HashIV。確認你的藍新帳號已通過審核並開通正式交易權限。
      </Tab>

      <Tab title="測試環境">
        使用藍新金流測試環境的 HashKey 與 HashIV。測試環境的交易不會產生實際扣款，適合開發階段使用。
      </Tab>
    </Tabs>
  </Step>

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

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

    將此 URL 設定到你的藍新金流後台的 **Notify URL** 欄位。

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

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

    帳獸收到藍新通知後，會將解析後的資料轉發到你指定的 URL，並附帶以下額外欄位：

    ```json theme={null}
    {
      "_event": "newebpay.notify",
      "_provider": "newebpay",
      "MerchantID": "...",
      "TradeNo": "...",
      "MerchantOrderNo": "...",
      "Amt": 1990,
      "PaymentType": "CREDIT",
      "PayTime": "2026-02-09 08:00:00"
    }
    ```
  </Step>

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

## 自動訂單建立

藍新金流通知到達後，帳獸會自動：

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

### 支付方式對應

| 藍新 PaymentType | 帳獸支付方式               |
| -------------- | -------------------- |
| CREDIT         | 信用卡（`credit_card`）   |
| VACC           | ATM 轉帳（`atm`）        |
| CVS            | 超商繳費（`cvs`）          |
| LINEPAY        | LINE Pay（`line_pay`） |

### 訂閱週期自動偵測

如果你有啟用 SaaS 指標模組，帳獸會嘗試從藍新交易的商品描述（ItemDesc）自動判斷訂閱週期：

| 商品描述關鍵字             | 對應週期               |
| ------------------- | ------------------ |
| 月繳、月費、monthly       | 月繳（`monthly`）      |
| 季繳、quarterly        | 季繳（`quarterly`）    |
| 半年繳、semi-annual     | 半年繳（`semi-annual`） |
| 年繳、年費、yearly、annual | 年繳（`yearly`）       |

<Tip>
  在藍新金流的商品描述中加入週期關鍵字（如「專業方案月繳」），帳獸就能自動偵測訂閱週期並正確計算 MRR。
</Tip>

## Notify 記錄

你可以在後台查看所有接收到的藍新金流通知記錄：

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

## 常見問題

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

    1. 藍新後台的 Notify URL 設定正確
    2. Notify URL 使用 HTTPS 協定
    3. 你的帳獸帳號狀態正常
    4. 藍新的交易確實已完成付款
  </Accordion>

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

  <Accordion title="測試環境的交易會建立訂單嗎？">
    會。測試環境的交易也會建立訂單記錄，方便你在開發階段驗證整合是否正確。你可以稍後刪除測試資料。
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="綠界科技" icon="credit-card" href="/integrations/ecpay">
    設定綠界科技金流整合。
  </Card>

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