Shopify POS 香港實體店整合教學：由硬件到對帳全流程

在香港開設 Shopify POS 實體店，核心步驟是：設定門市 Locations 與庫存分流、採購支援的讀卡機硬件、用 Custom Payment Types 接入八達通／FPS／AlipayHK 等本地支付、再以 Webhooks 與 Admin API 自動對帳。以下是完整的實作教學。

香港零售的難處不在 Shopify 本身,而在支付。全球大部分市場只需開啟 Shopify Payments 就能收卡,但香港門市的現金流分散在八達通、轉數快(FPS)、AlipayHK、WeChat Pay HK、EPS 與 Visa/Mastercard 之間。這篇教學會把整合拆成七個可執行步驟,並附上實際的 CLI 指令、shopify.extension.toml 設定與 GraphQL 查詢。同樣的架構模式也適用於台灣、新加坡與澳洲門市——只是本地支付清單不同。

開始前需要準備什麼?

動手前先確認以下條件齊備,否則中途會卡住:

1. Shopify 方案:Basic 或以上。多門市與進階 POS 功能(員工權限、匯出清單、本地取貨)需要 Shopify POS Pro,按門市另行收費(費用以 Shopify 官方定價頁為準,請自行核實當期價格與貨幣)。
2. Shopify Payments 可用性:香港屬於 Shopify Payments 支援地區,但讀卡機硬件的供應地區與支付地區是兩回事。下單前務必在 Shopify Hardware Store 確認可否寄送至香港地址。
3. 商業登記與收單商戶號:若使用本地收單(EPS、八達通商戶機),需向銀行或支付服務商申請獨立終端機。
4. 開發環境(如需自訂 POS 介面):Node.js 18+、Shopify CLI 3.x、一個 Development Store。
5. 庫存基準:上線前必須完成一次實體盤點,否則線上線下庫存會從第一天開始偏差。

安裝 CLI:

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

步驟一:建立門市 Location 與庫存分流

Shopify 的 Location 是所有 O2O 功能的地基。POS 裝置登入時會綁定一個 Location,所有銷售、退貨與庫存調整都掛在該 Location 下。

在 Admin 介面:Settings → Locations → Add location。填寫門市地址時,地區欄請選「Hong Kong SAR」並填寫完整分區(如 Causeway Bay, Hong Kong Island),因為本地取貨(Local Pickup)與 Shopify Markets 的運費規則會讀取這個欄位。

若要批次建立多間分店,用 Admin GraphQL API 較快:

1mutation CreateStore {
2  locationAdd(input: {
3    name: "銅鑼灣旗艦店"
4    address: {
5      address1: "500 Hennessy Road"
6      city: "Causeway Bay"
7      countryCode: HK
8      phone: "+85229000000"
9    }
10    fulfillsOnlineOrders: true
11  }) {
12    location { id name }
13    userErrors { field message }
14  }
15}

呼叫方式:

1curl -X POST "https://your-store.myshopify.com/admin/api/2025-01/graphql.json" \
2  -H "X-Shopify-Access-Token: $SHOPIFY_ADMIN_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d @create-location.json

關鍵決策:門市庫存要不要賣到線上? fulfillsOnlineOrders: true 代表線上訂單可以從門市庫存出貨。對只有一兩間店的品牌,這能減少缺貨;但對人手緊張的門市,會造成店員在繁忙時段被迫包裹出貨。較穩妥的做法是先設為 false,等本地取貨流程跑順了再開啟。

開啟本地取貨:Settings → Shipping and delivery → Local pickup,為每個 Location 設定備貨時間(香港常見設定為「Usually ready in 2 hours」)與取貨指示(建議中英雙語,因為確認電郵會原樣顯示)。

步驟二:選擇硬件與處理網絡環境

香港商場舖位的現實是:Wi-Fi 不穩、電源插座不足、櫃檯深度有限。硬件規劃請考慮:

核心設備

• iPad(第 9 代或以上)或 Android 平板:Shopify POS App 對 iPadOS 支援最完整,POS UI Extensions 在 iOS 與 Android 均可運行。
• Shopify 讀卡機(如 WisePad 3 / Tap to Pay):務必先在 Shopify Hardware Store 確認香港可否配送及支援的卡組織。
• 收據打印機:Star Micronics TSP100III(LAN 版本比藍牙版本穩定得多)。
• 錢箱與條碼掃描器:Socket Mobile S700 是 Shopify 官方列明相容的型號。

網絡

建議為 POS 設一條獨立的 4G/5G 備援線路。Shopify POS 有離線模式,但離線時只能接受現金與自訂付款方式,信用卡交易會被拒絕。在商場斷網時,這代表你只能收現金——所以第三步的本地支付設定其實也是一種營運保險。

步驟三:接入八達通、FPS 與電子錢包

這是香港整合的核心。Shopify POS 原生不支援八達通、AlipayHK 或 WeChat Pay HK,解法是外接終端機 + Custom Payment Type 記帳。

建立自訂付款方式

Settings → Payments → Manual payment methods,或在 POS 設定中:Settings → Payment settings → Custom payment types → Add custom payment type。

建議建立以下項目,命名要與銀行月結單對得上:

• 八達通 Octopus
• FPS 轉數快
• AlipayHK
• WeChat Pay HK
• EPS
• 現金 Cash

店員流程是:在外接終端機(八達通商戶機或支付服務商的多合一 QR 終端機)完成收款 → 在 Shopify POS 選擇對應的自訂付款方式 → 完成訂單。Shopify 會記錄金額與付款類型,但不會驗證款項是否真的收到——這就是對帳步驟存在的原因。

根據香港金融管理局公布的數字,轉數快(FPS)登記數目已逾 1,500 萬個,日均交易宗數持續上升;八達通卡公司亦表示流通卡數長期維持在三千萬張以上的水平。換言之,在香港門市只接受信用卡等同主動放棄相當比例的即場成交。

用 Order Metafield 記錄終端機參考號

為了讓對帳可追溯,建議在收銀後把終端機的交易參考號寫進訂單。先定義 metafield:

1mutation {
2  metafieldDefinitionCreate(definition: {
3    name: "終端機參考號"
4    namespace: "hkpay"
5    key: "terminal_ref"
6    type: "single_line_text_field"
7    ownerType: ORDER
8    access: { admin: MERCHANT_READ_WRITE }
9  }) {
10    createdDefinition { id }
11    userErrors { field message }
12  }
13}

然後用 POS UI Extension 讓店員在結帳後輸入(見步驟四)。

步驟四:用 POS UI Extension 自訂收銀流程

如果想讓店員在 POS 上直接輸入終端機參考號、查會員積分或列印中文禮品單,就要寫 POS UI Extension。

1npm init @shopify/app@latest -- --template remix
2cd my-pos-app
3shopify app generate extension --template pos_ui_extension --name hk-pos-tools

shopify.extension.toml:

1api_version = "2025-01"
2
3[[extensions]]
4name = "HK POS Tools"
5handle = "hk-pos-tools"
6type = "ui_extension"
7
8  [[extensions.targeting]]
9  target = "pos.purchase.post.action.render"
10  module = "./src/PostPurchase.tsx"
11
12  [[extensions.targeting]]
13  target = "pos.home.tile.render"
14  module = "./src/Tile.tsx"

src/PostPurchase.tsx —— 結帳後讓店員補錄參考號:

1import React, {useState} from 'react';
2import {
3  reactExtension,
4  Screen,
5  Navigator,
6  TextField,
7  Button,
8  useApi,
9} from '@shopify/ui-extensions-react/point-of-sale';
10
11const Extension = () => {
12  const api = useApi<'pos.purchase.post.action.render'>();
13  const [ref, setRef] = useState('');
14  const orderId = api.order.id;
15
16  const save = async () => {
17    await fetch('https://your-app.example.com/api/terminal-ref', {
18      method: 'POST',
19      headers: {'Content-Type': 'application/json'},
20      body: JSON.stringify({orderId, terminalRef: ref}),
21    });
22    api.action.dismiss();
23  };
24
25  return (
26    <Navigator>
27      <Screen name="TerminalRef" title="終端機參考號">
28        <TextField
29          label="八達通／FPS 參考號"
30          value={ref}
31          onChange={setRef}
32        />
33        <Button title="儲存" onPress={save} />
34      </Screen>
35    </Navigator>
36  );
37};
38
39export default reactExtension('pos.purchase.post.action.render', () => <Extension />);

本地開發與測試:

1shopify app dev
2# 在 Shopify POS App 登入同一個 development store
3# Settings → Apps → 啟用 Developer preview

預期結果:完成一筆測試訂單後,收據畫面會出現「終端機參考號」按鈕;按下後彈出輸入欄,儲存後資料寫入 order metafield。

部署:

1shopify app deploy

取捨提醒:每多一個收銀後步驟,就多幾秒排隊時間。如果門市高峰期人龍長,考慮改為每日收舖時用一張清單批次補錄,而不是逐單輸入。

步驟五:自動化每日對帳

自訂付款方式最大的風險是「POS 記了、錢沒到」。用 Webhook 把每筆 POS 訂單推到你的對帳系統。

註冊 webhook:

1mutation {
2  webhookSubscriptionCreate(
3    topic: ORDERS_CREATE
4    webhookSubscription: {
5      callbackUrl: "https://your-app.example.com/webhooks/orders-create"
6      format: JSON
7    }
8  ) {
9    webhookSubscription { id }
10    userErrors { field message }
11  }
12}

Node/Express 接收端(含 HMAC 驗證,必做):

1import express from 'express';
2import crypto from 'crypto';
3
4const app = express();
5
6app.post('/webhooks/orders-create',
7  express.raw({type: 'application/json'}),
8  (req, res) => {
9    const hmac = req.get('X-Shopify-Hmac-Sha256');
10    const digest = crypto
11      .createHmac('sha256', process.env.SHOPIFY_API_SECRET)
12      .update(req.body)
13      .digest('base64');
14
15    if (!crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(hmac))) {
16      return res.sendStatus(401);
17    }
18
19    const order = JSON.parse(req.body.toString());
20    const isPOS = order.source_name === 'pos';
21    const gateways = order.payment_gateway_names; // 例:["八達通 Octopus"]
22
23    if (isPOS && gateways.some(g => g.includes('八達通'))) {
24      queueReconciliation(order); // 與八達通商戶月結檔比對
25    }
26    res.sendStatus(200);
27  });

要注意 source_name 為 pos 代表來自 Shopify POS;線上訂單通常是 web。若要查某門市某日的全部交易:

1query {
2  orders(first: 100, query: "created_at:>=2026-01-15 AND location_id:gid://shopify/Location/123456") {
3    edges {
4      node {
5        name
6        totalPriceSet { shopMoney { amount currencyCode } }
7        transactions { gateway status amountSet { shopMoney { amount } } }
8      }
9    }
10  }
11}

沒有開發資源的團隊,可以先用 Shopify Flow 做最低限度的控制:觸發器 Order created → 條件 Payment gateway contains 八達通 且 Order total > 2000 → 動作 Send internal email 通知店長覆核。這不是對帳,但能攔住最貴的錯誤。

步驟六:員工權限與防損設定

POS Pro 支援 PIN 登入與細緻權限。至少要分開三層:

• 店員:可銷售、可查庫存;不可手動改價、不可退款、不可開錢箱不成交。
• 店長:可折扣(設上限)、可退款、可做庫存調整。
• 總部:可改設定、可匯出報表。

設定路徑:Settings → Users and permissions → POS staff,再於 POS App → Settings → Staff 指派 PIN。把「手動折扣」與「退款」設為需要店長 PIN 覆核,是香港多店零售最常見也最值得做的一項設定。

步驟七:上線前測試清單

逐項跑完再開門:

1. 用每一種自訂付款方式各完成一筆真實小額交易,確認報表分類正確。
2. 做一次部分退款(信用卡)與一次自訂付款退款,確認庫存回補。
3. 關掉 Wi-Fi,測試離線模式:確認只剩現金與自訂付款可用,重新連線後訂單會同步。
4. 線上下單 + 門市取貨,確認店員收到通知、庫存自 Location 扣減。
5. 列印中英文收據,確認中文字元沒有變亂碼(LAN 打印機需在 Star 設定工具中確認編碼)。
6. 匯出當日 Sales by payment method 報表,與終端機 settlement 報表對數。

常見問題排查

POS 顯示「This location has no inventory」:商品的 Inventory 未分配到該 Location。到 Products → Inventory → Edit locations,勾選對應門市。批次處理用 inventorySetQuantities mutation。

讀卡機無法配對:九成情況是藍牙與另一台 iPad 仍然配對中。先在舊裝置移除配對,再長按讀卡機重設。LAN 打印機找不到,先確認 iPad 與打印機在同一個 VLAN——商場的訪客 Wi-Fi 通常開了 client isolation,必須用自己的路由器。

自訂付款方式在報表中全部混在一起:代表命名重複或有空白字元差異(例如「FPS 轉數快」與「FPS轉數快」被視為兩個 gateway)。Gateway 名稱無法事後合併,只能停用舊的並重新對帳,所以命名規則要在第一天定好。

POS UI Extension 不出現:檢查三點——api_version 是否為 App 支援的版本、extension 是否已 deploy、POS App 是否為最新版本並重新登入。開發模式下還要確認裝置與 shopify app dev 在同一網絡。

多幣種門市顯示錯誤價格:若用 Shopify Markets 做跨境,POS 會跟隨 Location 所在市場的貨幣。香港門市應確保 HKD 為該市場的在地貨幣,並檢查 rounding rules。

把香港架構複製到其他亞太市場

同一套模式在區內其他市場可重用,換掉的只是支付清單:

• 台灣:LINE Pay、街口支付、悠遊卡;發票合規是獨立課題,通常需第三方電子發票服務串接。
• 新加坡:PayNow QR、NETS;PayNow 與 FPS 一樣適合用 Custom Payment Type + QR 終端機處理。
• 澳洲:卡支付滲透率高,Shopify Payments + Tap to Pay 覆蓋率最好,本地支付的補丁需求最少。
• 馬來西亞／印尼／菲律賓:QR 標準(DuitNow、QRIS)主導,整合思路與香港幾乎一致。

對於從美國、英國或歐盟進入亞洲的品牌,這代表一件事:POS 的技術主幹可以統一,差異化只發生在支付與稅務層。把這層抽象成「每個市場一份 payment mapping 設定檔」,比為每個市場重做一套 POS 省事得多。

曾有一個香港多品牌餐飲集團在導入 Shopify POS 時採用類似架構:門市 Location 分流 + 自訂付款方式 + Flow 通知店長覆核高額交易,開發端用 POS UI Extension 讓前線補錄終端機參考號。重點不在技術新穎,而在把「人手抄寫」收斂成一個欄位,讓對帳有可查的線索。

用 LLM 加速對帳與門市支援

2026 年值得加一層自動化:把八達通 settlement CSV、銀行 EPS 報表與 Shopify 訂單匯出丟進一個 LLM 驅動的比對流程,讓模型處理格式不一致的欄位(日期格式、商戶號前綴、中文店名)。規則引擎負責判斷「對得上/對不上」,LLM 只負責把雜亂輸入正規化——這個分工比讓模型直接做金額判斷安全得多。

同樣做法可用於門市支援:把 POS 操作手冊、退貨政策與常見錯誤訊息做成內部檢索,店員用中文提問即時取得答案,減少打電話回總部的次數。

Branch8 在香港、新加坡、台灣、越南、馬來西亞、印尼、菲律賓與澳洲設有交付團隊,協助品牌規劃 Shopify Plus 與 POS 的跨境門市架構、本地支付整合與對帳自動化。若你正在評估香港或亞太多市場的 O2O 落地方案,歡迎與我們談談你的門市流程。

Sources

• Shopify Help Center — Sell in person with Shopify POS
• Shopify.dev — POS UI Extensions
• Shopify.dev — Admin GraphQL API Reference
• Shopify — POS Hardware Store
• Hong Kong Monetary Authority — Faster Payment System
• Octopus Holdings — Corporate Information
• Census and Statistics Department, HKSAR — Retail Sales Statistics
• Star Micronics — TSP100 Series Support