Shopify Plus 香港 Atome 分期付款整合教學

在 Shopify Plus 整合 Atome 分期付款，核心步驟是：先在 Atome Merchant Portal 申請香港商戶帳號取得 API 金鑰，於 Shopify Admin 安裝 Atome Payment App 並綁定 Store ID，再於 Checkout 與產品頁加入分期金額提示，最後用 sandbox 測試單完成對帳驗證。

香港與東南亞的 BNPL（Buy Now, Pay Later／先買後付）滲透率在過去數年快速上升。根據 Worldpay《Global Payments Report》，BNPL 在亞太區電商交易金額的佔比持續擴大，而 Atome 是少數同時覆蓋香港、新加坡、馬來西亞、印尼、菲律賓、泰國與越南的區域性 BNPL 供應商。對於以香港為亞太樞紐、同時營運多個 Shopify Plus store 的品牌來說，Atome 的價值不只是多一個付款選項，而是用同一套商戶架構打通跨境結帳體驗。

本教學會逐步示範完整整合流程：前置條件、商戶申請、App 安裝、Checkout 設定、產品頁分期金額顯示（包含 Liquid 與 Checkout Extensibility 兩種做法）、Webhook 對帳、以及常見錯誤排查。

開始之前需要準備什麼？

整合 Atome 不是純技術工作，商務與合規前置條件往往比程式碼更花時間。建議在開發排期前先確認以下項目：

商戶端前置條件

1. 有效的香港商業登記（BR）與公司註冊證明書（CI）。Atome 在香港的商戶審批需要公司主體文件，個人賣家無法開通。
2. 香港銀行商業帳戶，用於接收 Atome 的結算款項。部分品牌會用新加坡主體收款，但香港店面的結算幣別建議維持 HKD 以避免匯兌與對帳落差。
3. 產品類別合規檢查。BNPL 供應商對受規管商品（例如藥品、虛擬貨幣、賭博相關、部分金融服務）有限制，Atome 的 Acceptable Use Policy 會列明禁售類別。
4. 客單價區間確認。Atome 在香港一般設有單筆交易的最低與最高金額門檻，低於下限的訂單不會顯示分期選項，這會直接影響你在產品頁的顯示邏輯。

技術端前置條件

1. Shopify Plus 方案（或至少 Shopify Advanced，視 App 支援而定）。Plus 的優勢在於可自訂 checkout.liquid（舊版）或使用 Checkout Extensibility 的 UI Extensions，對 BNPL 的 messaging 控制更細緻。
2. Shopify Partner / Dev store 一個，用於 sandbox 測試，避免直接在 production store 跑測試單。
3. Theme 版本確認。若使用 Online Store 2.0 theme（Dawn 系列），分期金額提示建議以 App Block 或 Section 形式嵌入，而非硬改 product.liquid。
4. 存取權限：Shopify Admin 的 Payments、Apps、Themes 權限，以及 Atome Merchant Portal 的 Admin 角色。

實務提醒：Shopify 已宣布 checkout.liquid 的日落時程，Plus 商戶需遷移至 Checkout Extensibility。若你的 store 仍在舊版 checkout，建議把 Atome 整合與 checkout 遷移一併排期，避免做兩次。

如何在 Atome Merchant Portal 取得 API 憑證？

完成商戶申請後，你會收到 Atome Merchant Portal 的登入資訊。取得憑證的流程大致如下：

1. 登入 Atome Merchant Portal，切換到正確的 Country / Region = Hong Kong。多市場品牌常見錯誤是在 SG entity 下建立 HK store，導致幣別與結算週期錯配。
2. 進入 Settings → Developer / API Keys。
3. 建立一組 Sandbox 憑證與一組 Production 憑證，分別記錄：

• MERCHANT_ID（或 Store ID）
• API_KEY
• API_SECRET（僅顯示一次，務必即時保存）

4. 設定 Callback / Webhook URL，指向你的中介服務或 Shopify App 的 endpoint。

建議把憑證存放在密鑰管理服務，而非 theme 檔案或 Git repo。若團隊跨香港、台灣、越南協作，使用 1Password Secrets Automation、AWS Secrets Manager 或 Doppler 都比在 Slack 傳遞安全。

一個簡化的環境變數設定範例：

1# .env.example — 切勿將實際值 commit 進版本庫
2ATOME_ENV=sandbox            # sandbox | production
3ATOME_MERCHANT_ID=hk_xxxxxxxx
4ATOME_API_KEY=pk_test_xxxxxxxxxxxx
5ATOME_API_SECRET=sk_test_xxxxxxxxxxxx
6ATOME_CURRENCY=HKD
7ATOME_CALLBACK_URL=https://api.yourbrand.com/webhooks/atome

驗證憑證是否有效，可先用一個最小的 API 呼叫測試（實際 endpoint 以 Atome 官方文件為準）：

1curl -X POST "$ATOME_API_BASE/v1/payments" \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer $ATOME_API_KEY" \
4  -d '{
5    "referenceId": "test-order-0001",
6    "amount": { "currency": "HKD", "value": 80000 },
7    "paymentMethod": "ATOME",
8    "callbackUrl": "https://api.yourbrand.com/webhooks/atome"
9  }'

預期回應會包含一個 redirectUrl 與交易 ID。若收到 401 Unauthorized，先確認 API key 的環境（sandbox key 不能打 production base URL，反之亦然）。

在 Shopify Plus 安裝與啟用 Atome 付款方式

Atome 在 Shopify 生態提供官方 App，多數情況下不需要自建整合。流程如下：

1. 在 Shopify Admin 進入 Apps → Shopify App Store，搜尋 Atome 官方 App 並安裝。
2. 安裝後進入 App 設定頁，填入 MERCHANT_ID 與 API 憑證，選擇 Hong Kong / HKD。
3. 回到 Settings → Payments，在 Additional payment methods 或 Alternative payment methods 區塊啟用 Atome。
4. 確認付款方式排序。Shopify 的付款方式順序會影響轉換，一般把本地主流方式（信用卡、Apple Pay、AlipayHK、FPS）放前，BNPL 放在信用卡之後但在冷門方式之前。
5. 儲存後，在前台以測試模式下單，確認 Checkout 頁出現 Atome 選項。

多市場 store 的架構選擇

若你同時營運香港、新加坡、馬來西亞站點，有兩種常見做法：

做法 A：Shopify Markets 單一 store 多市場

• 優點：單一 catalog、單一 theme、營運成本低。
• 限制：Atome 的商戶帳號是按國家/地區開立的，單一 store 需確保付款方式按 market 條件顯示。Shopify Payments 的 market-specific payment method 設定在這裡是關鍵。

做法 B：Shopify Plus 多 store（每市場一個）

• 優點：每個 store 綁定對應國家的 Atome 商戶帳號，結算、幣別、稅務都乾淨。
• 限制：theme 與 app 設定需要同步維護，建議以 GitHub integration + Shopify CLI 管理 theme 版本。

1# 用 Shopify CLI 將同一份 theme 推到多個市場 store
2shopify theme push --store hk-brand.myshopify.com --theme-id 1234567890
3shopify theme push --store sg-brand.myshopify.com --theme-id 9876543210

跨境品牌在這裡的取捨很實際：做法 A 省人力但付款邏輯會變複雜；做法 B 乾淨但維運工時乘以市場數。Branch8 在為一家港資多品牌零售集團規劃亞太站點時，採取的是混合方式——香港與台灣各自獨立 store（因為物流與付款差異大），東南亞市場則以 Shopify Markets 合併處理。

如何在產品頁顯示 Atome 分期金額？

BNPL 的轉換效益主要來自結帳前的 messaging，而不是結帳頁本身。若顧客在產品頁就看到「分 3 期，每期 HK$266」，加入購物車的意願會明顯不同。

方法一：Online Store 2.0 App Block（建議）

Atome 官方 App 通常會提供 App Block。在 Theme Editor：

1. 進入 Online Store → Themes → Customize。
2. 選擇 Product template。
3. 在價格區塊下方 Add block → Apps → Atome Instalment Message。
4. 設定字體大小、顏色、是否顯示 logo。

這個方法的好處是升級 theme 時不會被覆蓋。

方法二：手動 Liquid snippet（需自訂時使用）

若 App Block 不符合設計需求，可建立 snippets/atome-instalment.liquid：

1{% comment %}
2  snippets/atome-instalment.liquid
3  用法：{% render 'atome-instalment', price: product.selected_or_first_available_variant.price %}
4  price 為 Shopify 的「分」單位整數（cents）
5{% endcomment %}
6
7{%- assign atome_min = 10000 -%}   {%- comment -%} HK$100.00 最低門檻，依合約調整 {%- endcomment -%}
8{%- assign atome_max = 1000000 -%} {%- comment -%} HK$10,000.00 上限，依合約調整 {%- endcomment -%}
9{%- assign tenor = 3 -%}
10
11{%- if price >= atome_min and price <= atome_max -%}
12  {%- assign per_instalment = price | divided_by: tenor -%}
13  <div class="atome-instalment" data-atome-price="{{ price }}">
14    <img src="{{ 'atome-logo.svg' | asset_url }}" alt="Atome" width="56" height="16" loading="lazy">
15    <span>
16      分 {{ tenor }} 期，每期 {{ per_instalment | money }}
17    </span>
18    <button type="button" class="atome-info-trigger" aria-label="了解 Atome 分期詳情">?</button>
19  </div>
20{%- endif -%}

在 sections/main-product.liquid 的價格區塊後方引用：

1{% render 'atome-instalment',
2   price: product.selected_or_first_available_variant.price %}

處理 variant 切換後金額未更新

這是最常見的 bug。Shopify 的 variant 切換是前端行為，Liquid 已經渲染完畢，所以需要 JS 監聽：

1// assets/atome-instalment.js
2(function () {
3  const TENOR = 3;
4  const MIN = 10000;   // cents
5  const MAX = 1000000; // cents
6
7  function formatHKD(cents) {
8    return 'HK$' + (cents / 100).toLocaleString('en-HK', {
9      minimumFractionDigits: 2,
10      maximumFractionDigits: 2
11    });
12  }
13
14  function render(cents) {
15    const el = document.querySelector('.atome-instalment');
16    if (!el) return;
17    if (cents < MIN || cents > MAX) {
18      el.hidden = true;
19      return;
20    }
21    el.hidden = false;
22    el.querySelector('span').textContent =
23      `分 ${TENOR} 期，每期 ${formatHKD(Math.round(cents / TENOR))}`;
24  }
25
26  // Online Store 2.0 variant change event
27  document.addEventListener('variant:change', (e) => {
28    if (e.detail && e.detail.variant) render(e.detail.variant.price);
29  });
30
31  // Dawn 系列常見的 fallback：監聽 form 的 variant input
32  const form = document.querySelector('form[action*="/cart/add"]');
33  if (form) {
34    new MutationObserver(() => {
35      const id = form.querySelector('[name="id"]');
36      if (!id) return;
37      const variant = window.__productVariants?.find(v => String(v.id) === id.value);
38      if (variant) render(variant.price);
39    }).observe(form, { subtree: true, attributes: true, attributeFilter: ['value'] });
40  }
41})();

把 variant 資料注入 window.__productVariants：

1<script>
2  window.__productVariants = {{ product.variants | json }};
3</script>
4<script src="{{ 'atome-instalment.js' | asset_url }}" defer></script>

方法三：Checkout Extensibility UI Extension

Shopify Plus 商戶若要在 checkout 加入自訂 Atome 說明（例如分期條款、FAQ 連結），應使用 Checkout UI Extension 而非改 checkout.liquid：

1shopify app generate extension --type=checkout_ui_extension --name=atome-notice

1// extensions/atome-notice/src/Checkout.jsx
2import {
3  reactExtension,
4  Banner,
5  useTotalAmount,
6} from '@shopify/ui-extensions-react/checkout';
7
8export default reactExtension('purchase.checkout.block.render', () => <AtomeNotice />);
9
10function AtomeNotice() {
11  const total = useTotalAmount();
12  const cents = Math.round(total.amount * 100);
13  if (total.currencyCode !== 'HKD' || cents < 10000) return null;
14
15  const perInstalment = (total.amount / 3).toFixed(2);
16  return (
17    <Banner status="info" title="Atome 分期付款">
18      {`選擇 Atome 可分 3 期支付，每期 HK$${perInstalment}，0 利息。`}
19    </Banner>
20  );
21}

Webhook 與訂單對帳要怎麼設定？

BNPL 整合最容易出事的環節不是付款，而是對帳。Atome 的結算是淨額（扣除 MDR 手續費）入帳，與 Shopify 訂單的 gross amount 不一致，財務部門若沒有中介層會每月對到半夜。

接收 Atome callback

建立一個輕量 webhook 接收端（Node.js / Express 範例）：

1// server/webhooks/atome.js
2import express from 'express';
3import crypto from 'crypto';
4
5const router = express.Router();
6
7function verifySignature(rawBody, signature, secret) {
8  const expected = crypto
9    .createHmac('sha256', secret)
10    .update(rawBody)
11    .digest('hex');
12  return crypto.timingSafeEqual(
13    Buffer.from(expected),
14    Buffer.from(signature || '')
15  );
16}
17
18router.post('/atome',
19  express.raw({ type: 'application/json' }),
20  async (req, res) => {
21    const sig = req.get('X-Atome-Signature');
22    if (!verifySignature(req.body, sig, process.env.ATOME_API_SECRET)) {
23      return res.status(401).send('invalid signature');
24    }
25
26    const event = JSON.parse(req.body.toString('utf8'));
27
28    switch (event.status) {
29      case 'PAID':
30        await tagShopifyOrder(event.referenceId, 'atome-paid');
31        break;
32      case 'CANCELLED':
33      case 'EXPIRED':
34        await tagShopifyOrder(event.referenceId, 'atome-failed');
35        break;
36      case 'REFUNDED':
37        await tagShopifyOrder(event.referenceId, 'atome-refunded');
38        break;
39    }
40
41    // 必須快速回 200，否則 Atome 會重試
42    res.status(200).send('ok');
43  }
44);
45
46export default router;

回寫 Shopify 訂單標籤

用 Shopify Admin GraphQL API（2025-10 版本）加上 tag 與 metafield，方便後續在 Admin 搜尋與 Flow 觸發：

1mutation tagOrder($id: ID!, $tags: [String!]!) {
2  tagsAdd(id: $id, tags: $tags) {
3    node { id }
4    userErrors { field message }
5  }
6}

1curl -X POST "https://hk-brand.myshopify.com/admin/api/2025-10/graphql.json" \
2  -H "X-Shopify-Access-Token: $SHOPIFY_ADMIN_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{"query":"mutation { tagsAdd(id: \"gid://shopify/Order/123456789\", tags: [\"atome-paid\"]) { userErrors { message } } }"}'

自動化對帳的實務做法

1. 每日從 Atome Merchant Portal 匯出 settlement report（CSV）。
2. 以 referenceId 對應 Shopify order name。
3. 計算 gross - MDR = net，與銀行入帳比對。
4. 差異超過容忍值即推送 Slack 警報。

這一段近年很適合用 LLM 輔助：把欄位名稱不一致的 CSV（Atome、Shopify Payouts、銀行 statement）交給一個 mapping agent 先做欄位對齊，再進入確定性的數值比對。重點是金額比對本身不能交給 LLM——它負責 schema mapping，不負責算數。

測試與上線檢查清單

上線前請按以下順序驗證：

1. Sandbox 下單成功：confirm Checkout 出現 Atome、跳轉 Atome 頁面、回跳後訂單狀態為 Paid。
2. 低於門檻訂單：金額低於最低限額時，Atome 選項應不出現，產品頁 messaging 也應隱藏。
3. 高於上限訂單：同上，避免顧客選了才被拒。
4. Variant 切換：切換不同價位 variant，分期金額即時更新。
5. 折扣碼 / Gift card：套用折扣後，Checkout 的分期金額應以折後金額計算。
6. 部分退款：在 Shopify 退款後，確認 Atome 端同步收到 refund event。
7. 行動裝置：香港電商流量以行動為主，根據 Shopify 公布的 BFCM 數據，行動裝置長期佔全球 Shopify 結帳流量多數，務必在 iOS Safari 與 Android Chrome 各測一次 app switch 回跳。
8. 多語系：繁中 / 英文版本的 messaging 文案與條款連結都要存在。
9. Speed 檢查：用 Lighthouse 確認新增的 JS 沒有讓 LCP 惡化。

常見錯誤與排查

Checkout 沒有出現 Atome 選項

• 確認訂單幣別是 HKD。Atome HK 帳號不接受其他幣別。
• 確認訂單金額在合約門檻內。
• 確認顧客的 shipping address 國家為香港（部分設定會以地址判斷）。
• 確認 store 不在 password-protected 狀態下做 live 測試——部分 payment app 在此狀態會被阻擋。

回跳後訂單狀態停在 Pending

• 多數是 webhook 沒收到或驗簽失敗。檢查你的 endpoint 是否回 200，以及是否用 raw body 做 HMAC（用已 parse 的 JSON 重新 stringify 會導致簽章不符，這是最常見的坑）。
• 檢查 WAF / Cloudflare 規則是否擋下 Atome 的 callback IP。

產品頁分期金額與 Checkout 不一致

• 通常是前端沒把折扣、會員價或 Shopify Markets 的 price list 納入計算。建議 messaging 一律以 selected_or_first_available_variant.price 為準，並在 checkout 以實際 total 覆蓋。

Sandbox 可以、Production 失敗

• 檢查是否誤用 sandbox key 打 production endpoint。
• 檢查 Production 商戶帳號是否已通過 Atome 的最終審批（部分帳號會先開 sandbox，production 另行啟用）。

退款金額對不上

• BNPL 退款通常退回 gross amount，但 MDR 手續費是否退還依合約而定。上線前請向 Atome 客戶經理書面確認退款手續費政策，並在財務系統建立對應科目。

跨境擴張時的架構建議

香港站做完後，把同一套邏輯複製到新加坡、馬來西亞、台灣時，有幾個決策點值得先想清楚：

付款方式組合會因市場而異。 香港顧客偏好信用卡與 FPS、AlipayHK；印尼與菲律賓的 e-wallet 與 BNPL 比重更高。根據 Worldpay《Global Payments Report》，數位錢包在亞太區電商付款方式中佔比領先其他方式，BNPL 則在特定市場成長較快。不要把香港的付款排序直接複製到東南亞。

BNPL 監管在收緊。 新加坡金融管理局（MAS）支持的 BNPL 行業行為準則（Code of Conduct）對信貸上限與揭露有具體要求；澳洲則已將 BNPL 納入《National Consumer Credit Protection Act》框架。多市場品牌在設計 messaging 文案時，不能一份文案打天下——部分市場對「0 利息」「免手續費」等用詞有揭露規範。

對帳要集中，前端可以分散。 建議在中介層（例如一個輕量的 Node/Serverless service）統一收所有市場的 BNPL webhook，再分流寫回各 Shopify store。這樣財務只需要看一個 dashboard。

時區覆蓋是實質優勢。 以香港為基地、團隊分布於新加坡、台灣、越南與澳洲，意味著從 GMT+7 到 GMT+11 都有人可以接手 payment incident。對歐美品牌而言，這等於把亞太付款故障的平均回應時間壓到幾乎不需要等待隔夜。

常見設定值速查

環境：sandbox 用於全部開發與 UAT；production 僅限上線後。

幣別：香港 store 固定 HKD，不要靠 Shopify Markets 自動換算後再送給 Atome。

金額單位：Shopify Liquid 的 price 是 cents（整數）；Atome API 多數 endpoint 也用最小單位。混用元與分是常見的 100 倍誤差來源。

Webhook 重試：設計 handler 為 idempotent，以 referenceId + status 做去重鍵。

日誌保留：建議保留至少 13 個月的 webhook payload（去識別化後），以應付年度財務審計。

Branch8 團隊以香港為總部，在新加坡、台灣、越南、馬來西亞、印尼、菲律賓與澳洲都有交付人員，長期為亞太與歐美品牌處理 Shopify Plus 建置、付款整合與跨境結帳優化。如果你正在規劃香港或多市場的 BNPL 上線，歡迎與我們談談你的架構與對帳流程。

Sources

• Shopify — Payments Documentation
• Shopify.dev — Checkout UI Extensions
• Shopify.dev — Admin GraphQL API
• Atome — Official Site
• Worldpay — Global Payments Report
• Monetary Authority of Singapore
• Australian Securities & Investments Commission — Buy Now Pay Later
• Hong Kong Monetary Authority