Shopify Plus 香港 FPS 轉數快支付整合教學

1node -v
2# v20.11.1
3npm install -g @shopify/cli@latest
4shopify version
5# 3.x.x
6shopify auth logout && shopify app dev --reset

1curl -s -X POST "https://your-shop.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":"{ orders(first:1, sortKey:CREATED_AT, reverse:true){ nodes { name displayFinancialStatus transactions { gateway status amountSet { shopMoney { amount currencyCode } } } } } }"}'

1{"data":{"orders":{"nodes":[{"name":"#1042","displayFinancialStatus":"PAID",
2 "transactions":[{"gateway":"qfpay","status":"SUCCESS",
3 "amountSet":{"shopMoney":{"amount":"1880.00","currencyCode":"HKD"}}}]}]}}}

1shopify app init --name fps-payments-app
2cd fps-payments-app
3shopify app generate extension --template payments_extension
4# 選擇 Offsite payments

1[[extensions]]
2type = "payments_extension"
3name = "FPS (轉數快)"
4handle = "fps-offsite"
5
6  [extensions.payment_session]
7  url = "https://pay.example.com/shopify/payment_sessions"
8
9  [extensions.refund_session]
10  url = "https://pay.example.com/shopify/refund_sessions"
11
12  [extensions.targeting]
13  supported_countries = ["HK"]
14  supported_currencies = ["HKD"]
15  supports_deferred_payments = false
16  supports_installments = false
17  test_mode_available = true

1// server/routes/paymentSessions.js — Express 4, Node 20
2import crypto from "node:crypto";
3
4export function verifyShopifyHmac(req) {
5  const digest = crypto
6    .createHmac("sha256", process.env.SHOPIFY_API_SECRET)
7    .update(req.rawBody, "utf8")
8    .digest("base64");
9  const header = req.get("Shopify-Hmac-Sha256") || "";
10  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(header));
11}
12
13export async function createPaymentSession(req, res) {
14  if (!verifyShopifyHmac(req)) return res.status(401).send("bad hmac");
15
16  const { id, gid, amount, currency, test, payment_method } = req.body;
17  if (currency !== "HKD") return res.status(422).send("unsupported currency");
18
19  // 向 PSP 建立 FPS 交易（此處以泛用 REST 介面示意）
20  const psp = await fetch(`${process.env.PSP_BASE_URL}/v1/fps/charges`, {
21    method: "POST",
22    headers: {
23      "Authorization": `Bearer ${test ? process.env.PSP_TEST_KEY : process.env.PSP_LIVE_KEY}`,
24      "Content-Type": "application/json",
25      "Idempotency-Key": id            // 用 Shopify session id 做冪等鍵
26    },
27    body: JSON.stringify({
28      amount_cents: Math.round(Number(amount) * 100),
29      currency: "HKD",
30      reference: gid,
31      expires_in: 900                  // FPS QR 建議 10–15 分鐘有效期
32    })
33  }).then(r => r.json());
34
35  await db.sessions.insert({ shopify_session_id: id, psp_charge_id: psp.id, gid });
36
37  return res.status(201).json({ redirect_url: psp.hosted_qr_url });
38}

1const RESOLVE = `
2mutation PaymentSessionResolve($id: ID!) {
3  paymentSessionResolve(id: $id) {
4    paymentSession { id status { code } }
5    userErrors { field message }
6  }
7}`;
8
9const PENDING = `
10mutation PaymentSessionPending($id: ID!, $pendingExpiresAt: DateTime!, $reason: PaymentSessionStatePendingReason!) {
11  paymentSessionPending(id: $id, pendingExpiresAt: $pendingExpiresAt, reason: $reason) {
12    paymentSession { id status { code } }
13    userErrors { field message }
14  }
15}`;
16
17async function callPaymentsApi(shop, token, query, variables) {
18  const r = await fetch(`https://${shop}/payments_apps/api/2025-01/graphql.json`, {
19    method: "POST",
20    headers: { "X-Shopify-Access-Token": token, "Content-Type": "application/json" },
21    body: JSON.stringify({ query, variables })
22  });
23  return r.json();
24}
25
26export async function pspWebhook(req, res) {
27  // 1) 先驗 PSP 簽章（各家不同，通常是 HMAC-SHA256 over raw body）
28  if (!verifyPspSignature(req)) return res.status(401).end();
29
30  const { charge_id, status } = req.body;
31  const s = await db.sessions.findByPspChargeId(charge_id);
32  if (!s) return res.status(202).end();               // 未知交易，別回 5xx
33
34  if (status === "SUCCEEDED") {
35    await callPaymentsApi(s.shop, s.token, RESOLVE, { id: s.shopify_gid });
36  } else if (status === "AWAITING_SETTLEMENT") {
37    await callPaymentsApi(s.shop, s.token, PENDING, {
38      id: s.shopify_gid,
39      pendingExpiresAt: new Date(Date.now() + 24 * 3600 * 1000).toISOString(),
40      reason: "BUYER_ACTION_REQUIRED"
41    });
42  }
43  return res.status(200).end();
44}

1{"data":{"paymentSessionResolve":{"paymentSession":{
2  "id":"gid://shopify/PaymentSession/1234567890",
3  "status":{"code":"RESOLVED"}},"userErrors":[]}}}

1// fpsQr.js
2const tlv = (tag, value) =>
3  `${tag}${String(value.length).padStart(2, "0")}${value}`;
4
5function crc16ccitt(str) {
6  let crc = 0xffff;
7  for (const byte of Buffer.from(str, "utf8")) {
8    crc ^= byte << 8;
9    for (let i = 0; i < 8; i++) {
10      crc = crc & 0x8000 ? ((crc << 1) ^ 0x1021) & 0xffff : (crc << 1) & 0xffff;
11    }
12  }
13  return crc.toString(16).toUpperCase().padStart(4, "0");
14}
15
16export function buildFpsPayload({ guid, proxyType, proxyValue, amountHkd, reference, merchantName, mcc }) {
17  const account =
18    tlv("00", guid) +          // 由 HKICL / 銀行指派
19    tlv("01", proxyType) +     // FPS ID / 手機 / 電郵
20    tlv("02", proxyValue);
21
22  let payload =
23    tlv("00", "01") +                       // Payload Format Indicator
24    tlv("01", "12") +                       // 12 = 動態（單次使用）
25    tlv("26", account) +                    // Merchant Account Information
26    tlv("52", mcc) +
27    tlv("53", "344") +                      // HKD ISO 4217 numeric
28    tlv("54", amountHkd.toFixed(2)) +
29    tlv("58", "HK") +
30    tlv("59", merchantName.slice(0, 25)) +
31    tlv("60", "Hong Kong") +
32    tlv("62", tlv("05", reference));        // 訂單號，供對帳
33
34  payload += "6304";
35  return payload + crc16ccitt(payload);
36}

1node -e "import('./fpsQr.js').then(m=>console.log(m.buildFpsPayload({guid:'hk.example.psp',proxyType:'01',proxyValue:'1234567',amountHkd:1880,reference:'1042',merchantName:'DEMO STORE LTD',mcc:'5944'})))"
2# 000201010212262600...5303344540719...62080504104263047A2B

1// extensions/fps-qr/src/Checkout.jsx
2import { reactExtension, BlockStack, Text, Image, useOrder } from "@shopify/ui-extensions-react/checkout";
3
4export default reactExtension("purchase.thank-you.block.render", () => <FpsBlock />);
5
6function FpsBlock() {
7  const order = useOrder();
8  const src = `https://pay.example.com/fps-qr.png?order=${order?.id}`;
9  return (
10    <BlockStack border="base" padding="base" spacing="tight">
11      <Text emphasis="bold">請用銀行 App 掃描以下轉數快 QR 完成付款</Text>
12      <Image source={src} accessibilityDescription="FPS QR code" />
13      <Text appearance="subdued">備註欄請保留訂單編號 {order?.name}，QR 有效期 15 分鐘。</Text>
14    </BlockStack>
15  );
16}

1shopify app deploy
2# 於 Admin → Settings → Checkout → Customize 將 App block 加到 Thank you 頁

1mutation MarkPaid($id: ID!) {
2  orderMarkAsPaid(input: { id: $id }) {
3    order { id displayFinancialStatus }
4    userErrors { field message }
5  }
6}