台灣電商品牌 Shopify Plus 超商條碼繳費設定教學

在 Shopify Plus 上開通超商條碼繳費，實務做法是：先在綠界、藍新等台灣金流商後台申請 CVS 條碼/代碼繳費，再以 Payments App 或 offsite gateway 串接 Shopify，最後用 webhook 回寫付款狀態、並以 Shopify Flow 自動催繳與取消逾期訂單。

為什麼超商繳費仍是台灣電商不能省的選項

台灣的線上零售規模持續擴大，根據經濟部統計處的零售業營業額統計，2022 年零售業網路銷售額約新台幣 4,930 億元，且線上占比逐年上升。在這個市場裡，超商通路是一個難以被信用卡完全取代的支付與取貨節點——統一超商年報揭露全台 7-ELEVEN 門市數超過 6,800 家，全家便利商店官方資料顯示門市數超過 4,000 家，密度在全球名列前茅。

對跨境品牌來說，這件事常被低估。從倫敦或紐約總部看台灣，會直覺認為「信用卡滲透率高，開 Shopify Payments 就好」。但實際轉換數據通常會顯示：年輕族群、無卡族、以及對線上刷卡仍有疑慮的客層，會在結帳頁看不到超商選項時直接跳出。超商繳費同時解決了三件事——信任感、現金支付需求、以及與超商取貨（C2C/B2C 店配）的動線一致性。

本文用實作角度走完整個設定流程，包含前置條件、後台設定、程式碼、自動化與除錯，適用於 Shopify Plus（也大致適用於 Shopify Advanced，差別會標註）。

代碼繳費、條碼繳費、ATM 虛擬帳號差在哪裡？

三者在金流商後台常被歸在同一組「非即時付款」，但消費者體驗完全不同，選錯會直接影響客服量。

超商代碼繳費（CVS）

金流商回傳一組繳費代碼（通常 14 碼左右）。消費者到 7-ELEVEN ibon、全家 FamiPort、萊爾富 Life-ET、OK go 等機台輸入代碼，列印繳費單後到櫃台付款。優點是代碼可用簡訊、Email、LINE 傳遞；缺點是機台操作步驟多，長輩客層容易卡關。

超商條碼繳費（BARCODE）

金流商回傳三段條碼（Barcode1／Barcode2／Barcode3）。消費者把條碼列印出來，或在手機上出示，直接到櫃台刷條碼付款。省掉機台這一步，對熟悉超商繳水電費的客層最直覺。缺點是部分門市對手機螢幕條碼的掃描成功率受螢幕亮度、保護貼影響，且三段條碼在小螢幕上呈現需要額外設計。

ATM 虛擬帳號

回傳銀行代碼 + 16 碼虛擬帳號，消費者用網銀或實體 ATM 轉帳。金額上限通常高於超商，適合客單價較高的訂單。

實務建議：客單價低於超商單筆上限的訂單，同時開放代碼與條碼；高客單價品項（例如精品、3C）必須保留 ATM 虛擬帳號或信用卡做為 fallback。依綠界科技官方開發者文件，超商代碼與條碼繳費有單筆金額上限（目前為新台幣 2 萬元等級，實際數字以金流商當期公告為準），超過上限的訂單在送出建立請求時就會被拒絕，而不是在結帳頁被擋下——這是最常見的設計疏失。

開始之前要準備什麼？

1. Shopify Plus 或 Advanced 方案帳號，且已完成 Taiwan 市場設定（Markets 中新增台灣、貨幣 TWD）。
2. 台灣金流商正式帳號：綠界科技（ECPay）、藍新金流（NewebPay）、歐付寶或智付寶擇一。需備妥公司登記證明、負責人證件、銀行帳戶。審核通常需要數個工作天，跨境公司若無台灣公司實體，需先確認金流商是否接受境外商戶。
3. 測試環境金鑰：綠界提供 stage 測試站（MerchantID、HashKey、HashIV）；藍新提供測試商店代號與 HashKey/HashIV。
4. 一個可對外的 HTTPS endpoint：用於接收金流商的付款完成通知（背景回傳）。可以是 Cloudflare Workers、Vercel Function、或自架 Node/Express。
5. Shopify Admin API 存取權：建立 custom app，授予 read_orders、write_orders、write_merchant_managed_fulfillment_orders 權限，取得 Admin API access token。
6. 本地開發工具：Node.js 18+、Shopify CLI 3.x。

1npm install -g @shopify/cli@latest
2shopify version
3# 預期輸出：3.x.x

步驟一：在金流商後台開通超商繳費

以綠界為例，登入廠商後台後：

1. 進入「系統開發管理 → 系統介接設定」，取得 MerchantID、HashKey、HashIV。
2. 在「帳戶管理 → 收款方式設定」中，確認 CVS（超商代碼）與 BARCODE（超商條碼）已開通。若顯示待審核，代表風控尚未放行。
3. 設定「付款完成通知網址」（ReturnURL）與「取號完成通知網址」（PaymentInfoURL）。這兩個是不同的 endpoint：取號時金流商先回傳條碼／代碼，付款完成時才會再打一次。
4. 設定繳費期限（StoreExpireDate）。超商繳費以「天」為單位，一般設 3～7 天。期限越長，庫存被鎖住的時間越久。

藍新金流的對應設定在「商店管理 → 商店資料設定」，欄位名稱為 NotifyURL 與 CustomerURL，並使用 AES 加密傳輸而非 CheckMacValue，串接寫法不同，但流程邏輯一致。

步驟二：把金流接進 Shopify Plus

Shopify 不允許在結帳頁自行注入第三方付款表單，因此只有三條合法路徑，選擇會影響後續維運成本。

路徑 A：Payments App（推薦給長期經營台灣市場的品牌）

使用 Shopify 的 Payments Apps API 建立付款擴充，付款方式會原生出現在 Shopify Checkout 的付款區塊，享有完整的 checkout 分析、Shop Pay 相容性與退款流程。開發流程：

1shopify app init --template payments-app
2cd my-tw-payments-app
3shopify app dev

核心是實作 paymentSessionResolve 與 paymentSessionReject 兩個 GraphQL mutation。超商繳費屬於非即時付款，正確做法是在取號成功後先回 PENDING，等收到付款通知才 resolve：

1mutation PaymentSessionPending($id: ID!, $reason: PaymentSessionStatePendingReason!) {
2  paymentSessionPending(id: $id, pendingExpiresAt: "2026-02-01T00:00:00Z", reason: $reason) {
3    paymentSession { id status { code } }
4    userErrors { field message }
5  }
6}

1mutation PaymentSessionResolve($id: ID!) {
2  paymentSessionResolve(id: $id) {
3    paymentSession { id status { code } }
4    userErrors { field message }
5  }
6}

路徑 B：Offsite gateway（金流商官方 App）

綠界與藍新都在 Shopify App Store 或以私有 app 形式提供現成串接。安裝後在 設定 → 付款 → 其他付款方式 啟用即可。優點是幾天內就能上線，缺點是結帳頁會跳離 Shopify 網域到金流商取號頁，轉換率會受影響，且客製化空間小。

路徑 C：手動付款方式 + 外部取號（最低成本驗證）

在 設定 → 付款 → 手動付款方式 → 建立自訂付款方式 新增「超商條碼繳費」，訂單成立後為 pending，再用 webhook 觸發自建服務向金流商取號，把條碼寫回訂單 metafield 並寄出通知信。適合先驗證台灣市場需求、還不想投入 app 開發的品牌。

步驟三：向金流商取號並寫回訂單

以綠界為例，取號請求需要計算 CheckMacValue。這段是最常出錯的地方——排序規則、URL encode 的大小寫、以及特殊字元替換都必須完全一致。

1const crypto = require('crypto');
2
3function genCheckMacValue(params, hashKey, hashIV) {
4  const sorted = Object.keys(params)
5    .sort((a, b) => (a.toLowerCase() < b.toLowerCase() ? -1 : 1))
6    .map((k) => `${k}=${params[k]}`)
7    .join('&');
8
9  const raw = `HashKey=${hashKey}&${sorted}&HashIV=${hashIV}`;
10
11  const encoded = encodeURIComponent(raw)
12    .toLowerCase()
13    .replace(/%20/g, '+')
14    .replace(/%21/g, '!')
15    .replace(/%27/g, "'")
16    .replace(/%28/g, '(')
17    .replace(/%29/g, ')')
18    .replace(/%2a/g, '*');
19
20  return crypto.createHash('sha256').update(encoded).digest('hex').toUpperCase();
21}
22
23const payload = {
24  MerchantID: process.env.ECPAY_MERCHANT_ID,
25  MerchantTradeNo: 'SHP' + Date.now(),        // 限英數 20 碼內
26  MerchantTradeDate: '2026/01/15 14:30:00',   // 格式固定
27  PaymentType: 'aio',
28  TotalAmount: 1280,                          // 必須為整數
29  TradeDesc: encodeURIComponent('Shopify Order'),
30  ItemName: 'Order #1042',
31  ReturnURL: 'https://pay.example.com/ecpay/notify',
32  PaymentInfoURL: 'https://pay.example.com/ecpay/paymentinfo',
33  ChoosePayment: 'BARCODE',                   // 或 'CVS'
34  StoreExpireDate: 7,                         // BARCODE 以「天」計
35  EncryptType: 1,
36};
37
38payload.CheckMacValue = genCheckMacValue(payload, process.env.ECPAY_HASH_KEY, process.env.ECPAY_HASH_IV);

取號成功後，金流商會回傳 Barcode1、Barcode2、Barcode3（條碼）或 PaymentNo + ExpireDate（代碼）。把它寫進訂單 metafield，讓訂單狀態頁與通知信都能取用：

1mutation SetBarcode($metafields: [MetafieldsSetInput!]!) {
2  metafieldsSet(metafields: $metafields) {
3    metafields { key value }
4    userErrors { field message }
5  }
6}

1{
2  "metafields": [
3    { "ownerId": "gid://shopify/Order/5123456789", "namespace": "tw_payment", "key": "barcode_1", "type": "single_line_text_field", "value": "A612345678" },
4    { "ownerId": "gid://shopify/Order/5123456789", "namespace": "tw_payment", "key": "barcode_2", "type": "single_line_text_field", "value": "0412345678901234" },
5    { "ownerId": "gid://shopify/Order/5123456789", "namespace": "tw_payment", "key": "barcode_3", "type": "single_line_text_field", "value": "000000001280" },
6    { "ownerId": "gid://shopify/Order/5123456789", "namespace": "tw_payment", "key": "expire_at", "type": "date_time", "value": "2026-01-22T23:59:59+08:00" }
7  ]
8}

步驟四：接收付款通知並標記訂單已付款

金流商付款完成後會以 POST 打你的 ReturnURL。這支 endpoint 必須做三件事：驗簽、冪等處理、回傳指定字串。綠界要求回應純文字 1|OK，否則會重試通知。

1const express = require('express');
2const app = express();
3app.use(express.urlencoded({ extended: false }));
4
5app.post('/ecpay/notify', async (req, res) => {
6  const data = { ...req.body };
7  const received = data.CheckMacValue;
8  delete data.CheckMacValue;
9
10  const expected = genCheckMacValue(data, process.env.ECPAY_HASH_KEY, process.env.ECPAY_HASH_IV);
11  if (received !== expected) {
12    console.error('CheckMacValue mismatch', data.MerchantTradeNo);
13    return res.send('0|CheckMacValue Error');
14  }
15
16  if (data.RtnCode !== '1') {
17    return res.send('1|OK'); // 非成功狀態，僅記錄
18  }
19
20  const orderGid = await lookupOrderGid(data.MerchantTradeNo);
21  if (await alreadyPaid(orderGid)) return res.send('1|OK'); // 冪等保護
22
23  await markOrderAsPaid(orderGid);
24  return res.send('1|OK');
25});

標記付款完成使用 Admin GraphQL API（以 2025-01 版本為例）：

1async function markOrderAsPaid(orderGid) {
2  const query = `
3    mutation orderMarkAsPaid($input: OrderMarkAsPaidInput!) {
4      orderMarkAsPaid(input: $input) {
5        order { id displayFinancialStatus }
6        userErrors { field message }
7      }
8    }`;
9
10  const res = await fetch(`https://${SHOP}.myshopify.com/admin/api/2025-01/graphql.json`, {
11    method: 'POST',
12    headers: {
13      'Content-Type': 'application/json',
14      'X-Shopify-Access-Token': process.env.SHOPIFY_ADMIN_TOKEN,
15    },
16    body: JSON.stringify({ query, variables: { input: { id: orderGid } } }),
17  });
18  return res.json();
19}

預期回傳：

1{"data":{"orderMarkAsPaid":{"order":{"id":"gid://shopify/Order/5123456789","displayFinancialStatus":"PAID"},"userErrors":[]}}}

若你走的是路徑 A（Payments App），則不要呼叫 orderMarkAsPaid，而是呼叫 paymentSessionResolve，讓 Shopify 自行把交易狀態同步為已付款——兩者同時做會造成帳務重複。

步驟五：用 Shopify Flow 自動化催繳與逾期取消

超商繳費最大的營運成本不是串接，是「未付款訂單」。Shopify Plus 內建的 Flow 可以把這段完全自動化，不需要額外排程服務。

流程一：取號後 48 小時未付款 → 寄出提醒

1. Trigger：Order created
2. Condition：Order payment gateway names contains CVS 或 Barcode
3. Action：Wait 48 hours
4. Condition：Order financial status is not Paid
5. Action：Send internal email 或串接 LINE Notify / Klaviyo webhook

流程二：逾期未付款 → 取消訂單並回補庫存

1. Trigger：Scheduled time（每日 02:00）
2. Action：Get order data，篩選 financial_status:pending 且 created_at < -8d
3. Action：Cancel order，勾選 Restock inventory

建議把取消門檻設在繳費期限 +1 天，避免消費者在最後一天深夜繳費、通知延遲導致誤取消。此外，Flow 的 Wait 步驟在大量訂單時會排隊，若你單日有數千張待繳訂單，改用外部排程 + Bulk Operations API 會更穩定。

步驟六：結帳與訂單狀態頁的文案設計

技術串好只完成一半。台灣消費者在超商繳費上最常客訴的三件事，都可以在前端解決：

• 三段條碼要能在手機上完整顯示。用 Checkout Extensibility 的 purchase.thank-you.block.render extension 在訂單狀態頁渲染條碼圖，並提供「另存圖片」按鈕。建議同時提供 PDF 下載，因為部分門市仍要求紙本。
• 明確標示繳費期限與逾期後果。寫「請於 2026/01/22 23:59 前完成繳費，逾期訂單將自動取消並釋出庫存」，比寫「7 天內有效」有效得多。
• 條碼與代碼同時提供。若金流商允許，同一筆訂單同時給條碼與代碼，讓消費者自選通路。

1import { reactExtension, Banner, Text, BlockStack } from '@shopify/ui-extensions-react/checkout';
2
3export default reactExtension('purchase.thank-you.block.render', () => <CvsBlock />);
4
5function CvsBlock() {
6  return (
7    <BlockStack>
8      <Banner status="info" title="超商條碼繳費資訊">
9        <Text>請於期限前持條碼至 7-ELEVEN、全家、萊爾富或 OK 超商櫃台繳費。</Text>
10      </Banner>
11    </BlockStack>
12  );
13}

對帳與退款該怎麼處理？

超商繳費的金流不是即時入帳。金流商通常在 T+N 個工作天撥款，且會扣除每筆固定手續費（費率依合約，需向金流商確認當期公告）。這代表兩件事：

1. Shopify 的訂單「已付款」時間 ≠ 實際入帳時間。財務對帳必須以金流商的撥款明細為主，Shopify 訂單報表為輔。做法是每日以 Bulk Operations API 匯出當日 financial_status:paid 且 gateway 為超商的訂單，與金流商對帳檔比對 MerchantTradeNo。
2. 退款無法原路退回。超商付的是現金，退款必須走匯款或金流商的退款作業，並需要消費者提供銀行帳號。務必在退換貨政策頁面寫清楚，並在 Shopify 訂單上以 metafield 記錄退款帳號（注意個資處理，不要寫進 order note）。

1# 匯出當日超商付款訂單（REST，供財務快速核對）
2curl -s "https://$SHOP.myshopify.com/admin/api/2025-01/orders.json?financial_status=paid&created_at_min=2026-01-15T00:00:00+08:00" \
3  -H "X-Shopify-Access-Token: $SHOPIFY_ADMIN_TOKEN" | jq '.orders[] | {name, total_price, gateway}'

常見錯誤與排除方式

CheckMacValue Error（綠界 RtnCode 10200073）

九成的原因是編碼處理。檢查：參數是否全部參與計算（含空值欄位）、排序是否為不分大小寫的字典序、encodeURIComponent 後是否轉小寫、以及 .NET 風格的特殊字元替換是否完整。用綠界官方提供的線上檢查碼產生器比對同一組參數，能在五分鐘內定位問題。

取號成功但訂單一直是 Pending

先確認 PaymentInfoURL（取號通知）與 ReturnURL（付款通知）沒有設成同一支。再檢查你的 endpoint 是否回傳 1|OK——若回傳 JSON 或 HTTP 302，金流商會判定通知失敗並持續重試，而你的系統可能已經處理過，造成狀態不一致。

金額含小數導致取號失敗

台灣超商繳費只接受整數新台幣。若商店啟用多幣別，Shopify 換算後可能產生小數。在 Markets 的價格設定中為 TWD 開啟「價格調整與四捨五入」，把結尾設為整數。

訂單編號重複

MerchantTradeNo 在同一商店代號下必須唯一且不可重複送出。用 Shopify order id 加上時間戳記組合，並保留 mapping table，避免消費者重新整理頁面時重複取號。

手機條碼掃不過

條碼圖片寬度不足是主因。三段條碼建議各自渲染、寬度至少填滿螢幕、背景純白、關閉深色模式反轉。同時提供代碼繳費做為備援。

測試環境可以付款，正式環境失敗

檢查是否仍指向 stage API endpoint，以及正式 HashKey/HashIV 是否誤用測試值。另外，正式環境有風控：新商戶初期單日交易額度可能受限，需主動向金流商申請調高。

跨境品牌進台灣的營運考量

我們在協助一家透過經銷體系銷售的製造業品牌切換到 Shopify Plus 時，遇到的最大阻力不是技術，而是流程：總部的財務系統假設「訂單成立即已收款」，但超商繳費會產生一段 3～7 天的懸浮期，ERP 對接必須改以付款事件而非訂單事件觸發出貨與開票。這類跨市場的假設落差，通常比串接本身花更多時間。

幾個給海外總部的實務提醒：

• 電子發票是獨立工程。台灣的統一發票與載具規範由財政部電子發票整合服務平台管理，多數金流商提供加值服務，但開立時機必須與付款事件對齊，不能綁在訂單建立。
• 境外公司能否開戶要提早確認。若沒有台灣實體，可能需要透過本地代理或設立分公司，這會是專案的關鍵路徑。
• 時區與客服。超商繳費的尖峰在晚間與週末，客服排班若只有歐美時區覆蓋，逾期取消的爭議會累積。以香港、台灣、新加坡為基地的團隊能提供 GMT+8 原生覆蓋，並在同一時區內與金流商技術窗口溝通。
• AI 輔助的營運放大。待繳訂單的催繳訊息、客服回覆模板、以及對帳差異的初步歸因，都適合用 LLM 產生草稿後由人審核。重點是把判斷留給人，把重複性文字與比對交給自動化。

把超商繳費做好，本質上是把台灣消費者既有的線下習慣接進你的線上結帳流程。技術不難，難的是庫存、對帳、發票與客服這四條線要同時對齊。

Branch8 在香港、台灣、新加坡等地設有交付團隊，協助 APAC 與歐美品牌完成 Shopify Plus 的在地金流、物流與 ERP 串接。若你正在規劃台灣市場上線或既有站點的金流重構，歡迎與我們的團隊聊聊你的架構與時程。

Sources

• Shopify — Payments Apps API documentation
• Shopify Help Center — Payment methods
• Shopify Help Center — Shopify Flow
• Shopify — Admin GraphQL API reference
• 綠界科技 ECPay — 開發者技術文件
• 藍新金流 NewebPay — 官方網站
• 經濟部統計處 — 批發、零售及餐飲業統計
• 財政部電子發票整合服務平台