香港電商 PayMe for Business 整合 Shopify 教學

香港電商要在 Shopify 收 PayMe，實務上有三條路：用手動付款方式掛靜態／動態 QR 最快上線；透過支援 PayMe 的支付閘道（如 AsiaPay、Oceanpayment、2C2P）接入屬中間方案；若要全自動對帳與退款，則用 Shopify Payments Apps API 自建付款擴充，串接 PayMe for Business 的線上收款 API。

為什麼 PayMe 值得香港及跨境品牌認真處理？

香港消費者的付款習慣，和品牌總部在倫敦或紐約的同事想像中的「信用卡為王」有明顯落差。根據 Worldpay 的《Global Payments Report》，亞太區電子商務交易金額中，數碼錢包佔比已超過其他所有付款方式總和，是全球錢包滲透率最高的區域。香港金融管理局（HKMA）公布的儲值支付工具（SVF）季度統計亦顯示，本地 SVF 戶口數目以千萬計，交易宗數持續以零售及線上消費為主要構成。

PayMe 由滙豐營運，是香港少數同時具備 P2P 社交支付基因與商戶收款能力的錢包。對電商而言，它的價值不只在「多一個付款掣」：

• 降低棄單率：買家不用輸入 16 位卡號、CVV、再過 3DS，特別是手機流量佔比高的香港市場。
• 覆蓋無卡／不願用卡的客群：學生、年輕客群、以及不想把卡資料留在陌生網站的消費者。
• 退款與爭議成本結構不同於卡組織：沒有 chargeback 機制，但同時代表你要自己建立糾紛處理流程（這是 trade-off，後文會講）。

對海外品牌來說，PayMe 通常是「進入香港市場」整套本地化清單的其中一項——和繁體中文文案、本地物流（順豐、嘉里）、以及本地化尺寸表放在同一個工作流裡處理。

開工前要準備什麼？

在寫任何一行程式碼之前，先把以下項目齊備，否則你會在中途卡在合規審批而不是技術問題上。

商戶與帳戶層面

1. PayMe for Business 商戶帳戶：需要香港公司註冊證明書（CI）、商業登記（BR）、董事身分證明、以及滙豐商業戶口。線上收款（非店內 QR）通常需要額外申請並提供網站 URL、營運模式與貨品類別說明。
2. 網站必備頁面：PayMe 與絕大多數香港收單機構一樣，會檢查退款政策、送貨政策、條款細則、聯絡資料。Shopify 的預設 policy 範本要改成與你實際營運一致，否則審批會被退回。
3. Shopify 店鋪權限：你需要 store owner 或具 Settings → Payments 權限的帳戶；若走自建路線，還需要 Partner 帳戶與 collaborator access。

技術層面

• Node.js 18+（或任何你熟悉的後端 runtime）
• Shopify CLI 3.x：npm install -g @shopify/cli@latest
• 一個可公開存取的 HTTPS endpoint（開發期可用 cloudflared tunnel 或 Shopify CLI 內建 tunnel）
• PayMe for Business 開發者文件與沙盒憑證（由客戶經理／開發者入口發放；端點與參數名稱以你收到的版本為準，不要照抄網上舊文）

確認版本：

1shopify version
2# 預期輸出：3.x.x
3
4node -v
5# 預期輸出：v18.x.x 或以上

三條整合路線，怎樣選？

路線 A：Shopify 手動付款方式 + PayMe QR

適合：月訂單量低於數百張、剛開站驗證市場、或暫時等待閘道審批的品牌。

機制：Shopify 的 Manual payment method 會讓訂單以 payment_pending 狀態建立，你在後台收到 PayMe 入帳後手動標記為已付款。

代價：人手對帳、無法自動擷取付款、退款要在 PayMe App 另行操作、訂單狀態與實際金流會有時間差。

路線 B：第三方支付閘道代收

適合：已經在用（或願意用）AsiaPay PayDollar、Oceanpayment、2C2P、Global Payments 等收單服務的品牌。

機制：閘道提供 Shopify App 或 hosted checkout，PayMe 作為其中一個付款選項呈現。你與閘道簽約，閘道再與 PayMe 結算。

代價：多一層分潤與結算週期；付款頁面可能跳出 Shopify checkout，影響轉換與 analytics 歸因。

路線 C：自建 Shopify Payments App

適合：多店多市場、需要把 PayMe 與其他亞太錢包（PayNow、LINE Pay、DuitNow、QRIS）統一管理的集團。

機制：用 Shopify Payments Apps API 建立 offsite payment extension，買家在 checkout 選 PayMe → 跳轉到你的服務 → 你呼叫 PayMe API 產生付款 → 回調後用 GraphQL mutation 告訴 Shopify 付款成功。

代價：開發與維運成本最高，且 payments app 需要通過 Shopify 審核才能公開上架（自用 custom app 則走 organization 內部安裝）。

路線 A 實作：30 分鐘內讓 PayMe 出現在 checkout

1. 在 Shopify 後台進入 Settings → Payments → Manual payment methods → Create custom payment method。
2. 名稱填 PayMe (HSBC)。
3. Additional details 欄位貼入付款指示，例如：

1請用 PayMe App 掃描以下 QR 碼，或搜尋 PayMe ID：@yourbrandhk
2付款時請在備註填寫訂單編號（例如 #1042）。
3我們會在收到款項後 1 個工作天內確認訂單並安排出貨。

4. Payment instructions 欄位重複一次同樣指示（這段會出現在 order confirmation email 與 thank-you page）。

QR 碼無法直接嵌進 Manual payment 欄位，實務做法是把 PayMe 收款連結（PayMe for Business 可產生 payme.hsbc/yourbrand 類型的連結）放進 thank-you page。用 Shopify 的 Settings → Checkout → Order status page → Additional scripts：

1<div id="payme-box" style="display:none;padding:16px;border:1px solid #ddd;border-radius:8px">
2  <p>請用 PayMe 支付 <strong id="payme-amount"></strong>，備註填寫訂單編號 <strong id="payme-order"></strong>。</p>
3  <a id="payme-link" href="#" target="_blank" rel="noopener">開啟 PayMe 付款</a>
4</div>
5<script>
6  (function () {
7    var gateway = "{{ order.gateway | default: '' }}";
8    if (gateway.toLowerCase().indexOf('payme') === -1) return;
9
10    var amount = "{{ order.total_price | money_without_currency }}";
11    var orderName = "{{ order.name }}";
12    var box = document.getElementById('payme-box');
13
14    document.getElementById('payme-amount').textContent = 'HK$' + amount;
15    document.getElementById('payme-order').textContent = orderName;
16    document.getElementById('payme-link').href =
17      'https://payme.hsbc/yourbrand?amount=' + encodeURIComponent(amount);
18    box.style.display = 'block';
19  })();
20})
21</script>

注意：Additional scripts 在 checkout extensibility 升級後將被 Checkout UI extensions 取代。若你的店已遷移至 Checkout Extensibility，請改用 purchase.thank-you.block.render extension target，邏輯相同但以 React 撰寫。

預期結果：買家在 checkout 看到「PayMe (HSBC)」選項 → 下單後訂單狀態為 Payment pending → 你在 PayMe for Business App 看到入帳 → 回 Shopify 訂單頁按 Mark as paid。

把手動對帳半自動化

人手對帳是路線 A 的主要痛點。一個可行的折衷：把 PayMe 交易記錄匯出 CSV，用腳本比對備註欄的訂單編號，再透過 Admin API 批次標記付款。

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 '{"query":"mutation { orderMarkAsPaid(input: {id: \"gid://shopify/Order/1234567890\"}) { order { id displayFinancialStatus } userErrors { field message } } }"}'

預期回應：

1{
2  "data": {
3    "orderMarkAsPaid": {
4      "order": { "id": "gid://shopify/Order/1234567890", "displayFinancialStatus": "PAID" },
5      "userErrors": []
6    }
7  }
8}

這正是 2026 年「AI 增補營運」最務實的切入點之一：備註欄經常被買家填成「1042」「訂單1042」「order #1042」甚至打錯一位數，純 regex 匹配會漏。把金額、時間窗、備註文字一併丟給 LLM 做模糊配對，再由人手覆核例外項，比起訓練一個客服每天肉眼核對兩百筆更可靠，也不需要為此加人。

路線 B 實作：透過支付閘道接入 PayMe

流程上與接任何第三方 gateway 無異，但有幾個香港特有的檢查點。

1. 與閘道簽約並確認 PayMe 已在你的 MID 下開通。不要假設「閘道支援 PayMe」等於「你的帳戶已開通 PayMe」——這兩件事通常要分開申請。
2. 在 Shopify 安裝閘道的官方 App（Settings → Payments → Add payment methods → 搜尋閘道名稱）。若閘道只提供 Shopify 的 "Third-party providers" 清單選項，則在 Payments 設定頁選擇該供應商並填入 Merchant ID 與 secret。
3. 設定回調 URL：多數閘道需要你在其後台填 https://your-store.myshopify.com/... 的 return/notify URL，Shopify App 一般會自動帶入。
4. 確認貨幣與 settlement：PayMe 只處理 HKD。若你的 Shopify 店以 USD 為基準貨幣並用 Shopify Markets 做多幣種，要確認閘道收到的是 HKD presentment amount，否則會出現四捨五入差額導致付款失敗。

測試要跑的最小集合

• HKD 訂單，含運費與折扣碼
• 金額含小數（例如 HK$288.50）
• 買家中途取消付款 → 訂單應維持 pending 或自動取消，不應出現「已付款但未入帳」
• 部分退款 → 確認閘道與 PayMe 兩邊紀錄一致

路線 C 實作：用 Payments Apps API 自建 PayMe 擴充

這是最完整但最重的方案。Shopify 的 offsite payment 流程是：buyer 在 checkout 選你的付款方式 → Shopify 向你的 app 發出 payment session → 你回傳一個 redirect URL → buyer 在你的頁面完成 PayMe 付款 → 你用 GraphQL mutation 回報結果 → Shopify 完成訂單。

1. 建立 app 與 extension

1shopify app init --name payme-hk-gateway
2cd payme-hk-gateway
3shopify app generate extension --template payments_extension
4# 選擇 "Offsite payments"

2. 設定 extension

extensions/payme-offsite/shopify.extension.toml：

1api_version = "2025-01"
2
3[[extensions]]
4name = "PayMe (HSBC)"
5handle = "payme-offsite"
6type = "payments_extension"
7
8  [extensions.payment_session]
9  start_url = "https://pay.yourdomain.com/shopify/payment-session"
10  refund_session_url = "https://pay.yourdomain.com/shopify/refund-session"
11  void_session_url = "https://pay.yourdomain.com/shopify/void-session"
12
13  [extensions.targeting]
14  supported_countries = ["HK"]
15  supported_payment_methods = ["payme"]
16  test_mode_available = true
17  merchant_label = "PayMe"
18  supports_oversell_protection = false
19  supports_installments = false
20  supports_deferred_payments = false

部署：

1shopify app deploy
2# 預期輸出：Extension "payme-offsite" deployed to Shopify

3. 處理 payment session 並驗證 HMAC

Shopify 會以 POST 把 session 推給你的 start_url，並附上 Shopify-Hmac-Sha256 header。永遠先驗證簽章再處理 payload。

1import express from "express";
2import crypto from "crypto";
3
4const app = express();
5app.use(express.raw({ type: "application/json" }));
6
7function verifyShopifyHmac(req) {
8  const received = req.get("Shopify-Hmac-Sha256") || "";
9  const digest = crypto
10    .createHmac("sha256", process.env.SHOPIFY_API_SECRET)
11    .update(req.body)
12    .digest("base64");
13  const a = Buffer.from(received);
14  const b = Buffer.from(digest);
15  return a.length === b.length && crypto.timingSafeEqual(a, b);
16}
17
18app.post("/shopify/payment-session", async (req, res) => {
19  if (!verifyShopifyHmac(req)) return res.status(401).send("Invalid HMAC");
20
21  const session = JSON.parse(req.body.toString("utf8"));
22  const { id, gid, amount, currency, test, payment_method } = session;
23
24  if (currency !== "HKD") {
25    return res.status(422).json({ error: "PayMe supports HKD only" });
26  }
27
28  // 向 PayMe for Business 建立一筆線上收款
29  // 實際端點、欄位名稱與認證方式，以你收到的 PayMe 開發者文件為準
30  const payme = await createPayMeCharge({
31    merchantReference: id,
32    totalAmount: amount,
33    currencyCode: "HKD",
34    isTestMode: test,
35    notifyUrl: "https://pay.yourdomain.com/payme/webhook",
36    redirectUrl: `https://pay.yourdomain.com/payme/return?session=${id}`
37  });
38
39  await db.sessions.insert({
40    shopifySessionId: id,
41    shopifySessionGid: gid,
42    paymeRequestId: payme.requestId,
43    amount,
44    status: "PENDING"
45  });
46
47  return res.status(201).json({ redirect_url: payme.webLink });
48});

預期行為：回傳 201 與 redirect_url 後，Shopify 會把買家導向該連結；桌面版應顯示 QR 碼供 PayMe App 掃描，手機版應嘗試 app-to-app 喚起。

4. 接收 PayMe 回調並 resolve session

1app.post("/payme/webhook", express.json(), async (req, res) => {
2  // 依 PayMe 文件驗證其簽章（header 名稱以文件為準）
3  if (!verifyPayMeSignature(req)) return res.sendStatus(401);
4
5  const { requestId, status, paymentId } = req.body;
6  const record = await db.sessions.findOne({ paymeRequestId: requestId });
7  if (!record) return res.sendStatus(404);
8
9  if (status === "COMPLETED") {
10    await resolveShopifySession(record.shopifySessionGid, paymentId);
11  } else if (status === "EXPIRED" || status === "CANCELLED") {
12    await rejectShopifySession(record.shopifySessionGid, "PROCESSING_ERROR");
13  }
14
15  return res.sendStatus(200);
16});

Resolve 的 GraphQL mutation（打向 https://{shop}.myshopify.com/payments_apps/api/2025-01/graphql.json）：

1mutation PaymentSessionResolve($id: ID!, $authorizationExpiresAt: DateTime) {
2  paymentSessionResolve(id: $id, authorizationExpiresAt: $authorizationExpiresAt) {
3    paymentSession {
4      id
5      state {
6        ... on PaymentSessionStateResolved { code }
7      }
8      nextAction {
9        action
10        context { ... on PaymentSessionActionsRedirect { redirectUrl } }
11      }
12    }
13    userErrors { field message }
14  }
15}

1async function resolveShopifySession(gid) {
2  const r = await fetch(
3    `https://${SHOP}.myshopify.com/payments_apps/api/2025-01/graphql.json`,
4    {
5      method: "POST",
6      headers: {
7        "Content-Type": "application/json",
8        "X-Shopify-Access-Token": process.env.SHOPIFY_ACCESS_TOKEN
9      },
10      body: JSON.stringify({ query: RESOLVE_MUTATION, variables: { id: gid } })
11    }
12  );
13  const json = await r.json();
14  const next = json.data?.paymentSessionResolve?.paymentSession?.nextAction;
15  // next.context.redirectUrl 就是要把買家送回去的 Shopify URL
16  return next?.context?.redirectUrl;
17}

預期輸出：state.code 為 RESOLVED，nextAction.action 為 REDIRECT，且 redirectUrl 指向 Shopify 的 thank-you page。把買家導向該 URL，訂單即顯示為已付款。

付款失敗時改用 paymentSessionReject，並傳入 reason（例如 PROCESSING_ERROR、RISKY）。退款則在 refund_session_url 收到請求後，呼叫 PayMe 退款 API，成功後以 refundSessionResolve 回報。

5. 本地測試

1shopify app dev
2# 預期輸出：Preview URL + tunnel URL（例如 https://xxxx.trycloudflare.com）

把 tunnel URL 暫時填入 shopify.extension.toml 的 start_url，在 development store 的 Settings → Payments 啟用你的 app，勾選 Test mode，然後下一張 HK$1.00 的測試單。

退款、對帳與財務流程怎樣處理？

PayMe 沒有卡組織的 chargeback 機制，這同時是優點與風險。

• 優點：你不會因為買家向發卡行爭議而被強制扣款，爭議成本較可預期。
• 風險：買家若聲稱未收貨，你沒有卡組織的舉證框架可依循，爭議完全落在你自己的客服政策上。因此送貨證明（簽收、追蹤號、POD 影像）的保存紀律要比做卡單時更嚴格。

實務建議：

1. 在 Shopify 訂單加上 metafield 記錄 PayMe 的 paymentId，退款時可追溯。
2. 結算週期與信用卡不同，記帳時用獨立的 clearing account，不要和卡單混在同一條 GL。
3. 若用 Xero 或 QuickBooks，把 PayMe 的每日結算額與 Shopify payouts 分開匯入，月結時差異才查得出來。

常見錯誤與排查

401 Invalid HMAC

九成是因為你在驗證前已經把 body 解析成 JSON。Express 中必須用 express.raw() 取得原始 buffer，express.json() 會改變位元組順序與空白，簽章永遠不會吻合。

買家付了款但訂單仍是 pending

檢查順序：PayMe webhook 有沒有送達（看你的 access log）→ 你有沒有成功呼叫 paymentSessionResolve → mutation 回應的 userErrors 是什麼。最常見是 session 已經逾時（Shopify payment session 有存活時限），此時應走人手補單流程，不要重試 resolve。

金額不符導致 PayMe 拒單

Shopify 傳來的 amount 是字串（例如 "288.50"），部分 API 期望的是最小貨幣單位整數（28850）。轉換時用 decimal 函式庫，不要用 parseFloat 再乘 100——浮點誤差會在某些金額產生 1 cent 差異。

手機無法喚起 PayMe App

通常是因為你的 redirect 頁面在 iframe 內渲染，或是 universal link 被 in-app browser（Facebook / Instagram 內建瀏覽器）攔截。解法是在偵測到 in-app browser 時，提示用家「以 Safari / Chrome 開啟」，並同時提供 QR 碼作後備。

Test mode 下交易一直失敗

確認 test_mode_available = true 已部署，且你傳給 PayMe 的是沙盒憑證而非生產憑證。Shopify 的 session payload 內 test: true 必須對應到 PayMe 沙盒環境，兩邊 mismatch 會得到含糊的錯誤訊息。

這套模式怎樣延伸到其他亞太市場？

PayMe 不會是你唯一要接的錢包。如果品牌計劃在亞太多市場開站，值得在架構上預留抽象層：一個統一的 payment orchestration 服務，對 Shopify 只暴露標準的 payments app 介面，對下游則接各市場的本地方案。

• 新加坡：PayNow QR（透過 Stripe、HitPay 或銀行直連）
• 台灣：LINE Pay、街口支付、以及仍佔相當份額的超商取貨付款
• 馬來西亞：DuitNow QR、FPX 網銀轉帳
• 印尼：QRIS（央行統一 QR 標準）、GoPay、OVO
• 澳洲／紐西蘭：PayID、以及 BNPL（Afterpay、Zip）

Branch8 曾為一個在香港、台灣與東南亞同步營運的多品牌零售集團處理這類工作：同一套 Shopify Plus 架構下，用 Shopify Markets 分流各市場 storefront，再以一組共用的 payments app 配置不同市場的本地錢包，避免每開一個市場就重寫一次結帳邏輯。這種做法的 trade-off 很明確——前期架構投入較高，但新增市場時的邊際成本顯著下降，而且付款失敗率可以在同一個 dashboard 比較。

跨境團隊的另一個現實優勢是時區。香港與新加坡的工程團隊覆蓋亞太營業時段，悉尼團隊接手早上，歐洲總部上班時已經看到夜間交易異常的處理紀錄——對於付款這種「壞掉就立即流失營收」的環節，這種接力比起單一時區的 on-call 更實際。

上線後要持續監控什麼？

1. 每個付款方式的 checkout completion rate：在 Shopify Analytics 用 Sessions converted 分 payment method 比較，若 PayMe 明顯低於卡單，通常是 redirect 體驗出了問題。
2. Webhook 失敗率：對 /payme/webhook 設 alert，連續失敗應觸發 PagerDuty 或 Slack 通知。
3. Pending 訂單年齡分佈：超過 24 小時仍 pending 的訂單應自動取消並釋放庫存。
4. 退款處理時間：PayMe 退款到帳時間與卡單不同，客服 SLA 文案要寫清楚，否則 WhatsApp 查詢量會上升。

如果你正在規劃香港或亞太多市場的 Shopify 付款架構，Branch8 的香港團隊與新加坡、台灣、越南、澳洲的交付團隊，可以協助評估三條整合路線的成本結構、處理支付擴充開發與對帳自動化。歡迎到 branch8.com 聯絡我們討論你的市場組合與現有技術堆疊。

Sources

• Shopify.dev — Payments Apps
• Shopify.dev — Payments Apps API Reference
• Shopify Help Center — Manual Payment Methods
• PayMe from HSBC — Business
• Hong Kong Monetary Authority — Stored Value Facilities Statistics
• Worldpay — Global Payments Report
• AsiaPay — Payment Gateway Solutions
• Census and Statistics Department, HKSAR — Retail Sales Statistics