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

1# Node.js 20 LTS 以上
2node -v
3# v20.11.0
4
5npm install -g @shopify/cli@latest
6shopify version
7# 3.x

1npm init @shopify/app@latest -- --template=payments_app
2cd fps-payments-app
3shopify app generate extension --template=payments_offsite --name="fps-hk"

1api_version = "2026-01"
2
3[[extensions]]
4name = "FPS (轉數快)"
5type = "payments_extension"
6handle = "fps-hk"
7
8  [extensions.payment_session]
9  url = "https://pay.yourdomain.com/fps/sessions"
10
11  [extensions.refund_session]
12  url = "https://pay.yourdomain.com/fps/refunds"
13
14  [extensions.void_session]
15  url = "https://pay.yourdomain.com/fps/voids"
16
17  [extensions.targeting]
18  merchant_label = "轉數快 FPS"
19  supported_countries = ["HK"]
20  supported_payment_methods = ["offsite"]
21  supports_deferred_payments = false
22  supports_installments = false
23  test_mode_available = true
24
25  [[extensions.targeting.merchant_label_translations]]
26  locale = "zh-TW"
27  label = "轉數快 FPS"
28
29  [[extensions.targeting.merchant_label_translations]]
30  locale = "en"
31  label = "FPS (Faster Payment System)"

1shopify app deploy
2# ✔ Deployed to Shopify
3# Extension: fps-hk (payments_extension) — version 1

1// verify.js
2import crypto from 'node:crypto';
3
4export function verifyShopifyHmac(rawBody, hmacHeader, secret) {
5  const digest = crypto
6    .createHmac('sha256', secret)
7    .update(rawBody, 'utf8')
8    .digest('base64');
9
10  const a = Buffer.from(digest);
11  const b = Buffer.from(hmacHeader || '');
12  return a.length === b.length && crypto.timingSafeEqual(a, b);
13}

1// server.js (Express 5)
2import express from 'express';
3import { verifyShopifyHmac } from './verify.js';
4import { createFpsOrder } from './psp.js';
5
6const app = express();
7app.use('/fps', express.raw({ type: 'application/json' }));
8
9app.post('/fps/sessions', async (req, res) => {
10  const raw = req.body.toString('utf8');
11  if (!verifyShopifyHmac(raw, req.get('X-Shopify-Hmac-Sha256'), process.env.APP_SECRET)) {
12    return res.status(401).send('Invalid HMAC');
13  }
14
15  const s = JSON.parse(raw);
16  // s.id, s.gid, s.amount, s.currency, s.test, s.group,
17  // s.payment_method, s.customer, s.proposed_at
18
19  if (s.currency !== 'HKD') {
20    return res.status(200).json({ error: 'UNSUPPORTED_CURRENCY' });
21  }
22
23  // reference 建議編碼店碼 + 訂單號，長度 <= 25，只用英數
24  const reference = `HK${s.group.replace(/[^A-Za-z0-9]/g, '').slice(-14)}`;
25
26  const pspOrder = await createFpsOrder({
27    amount: s.amount,          // 字串，如 "1280.00"
28    currency: s.currency,
29    reference,
30    idempotencyKey: s.id,      // 極重要：Shopify 會重試
31    expiresInSeconds: 900,
32    testMode: Boolean(s.test),
33  });
34
35  await db.sessions.put({
36    shopifySessionId: s.id,
37    shopifyGid: s.gid,
38    pspOrderId: pspOrder.id,
39    reference,
40    amount: s.amount,
41    status: 'PENDING',
42  });
43
44  return res.status(201).json({
45    redirect_url: `https://pay.yourdomain.com/fps/qr/${pspOrder.id}`,
46  });
47});

1// emv.js — 僅示範結構與 CRC；實際 Merchant ID / FPS ID 由收單機構提供
2function tlv(id, value) {
3  return id + String(value.length).padStart(2, '0') + value;
4}
5
6function crc16(payload) {
7  let crc = 0xFFFF;
8  for (const byte of Buffer.from(payload, 'utf8')) {
9    crc ^= byte << 8;
10    for (let i = 0; i < 8; i++) {
11      crc = (crc & 0x8000) ? ((crc << 1) ^ 0x1021) & 0xFFFF : (crc << 1) & 0xFFFF;
12    }
13  }
14  return crc.toString(16).toUpperCase().padStart(4, '0');
15}
16
17export function buildFpsQr({ fpsId, merchantName, city, amount, reference }) {
18  let p = '';
19  p += tlv('00', '01');                         // Payload Format Indicator
20  p += tlv('01', '12');                         // 12 = dynamic QR（每筆唯一）
21  p += tlv('26', tlv('00', 'hk.com.hkicl') + tlv('02', fpsId));
22  p += tlv('52', '0000');                       // MCC，依收單機構指示
23  p += tlv('53', '344');                        // HKD = 344 (ISO 4217)
24  p += tlv('54', amount);                       // 動態金額
25  p += tlv('58', 'HK');
26  p += tlv('59', merchantName.slice(0, 25));
27  p += tlv('60', city.slice(0, 15));
28  p += tlv('62', tlv('05', reference));          // Bill Number / Reference
29  p += '6304';
30  return p + crc16(p);
31}

1000201010212262400121hk.com.hkicl0210123456789520400005303344540
271280.005802HK5910BRAND LTD6009Hong Kong62110507HK000123 6304A1B2

1app.post('/fps/psp-webhook', async (req, res) => {
2  const evt = JSON.parse(req.body.toString('utf8'));
3  if (!verifyPspSignature(req)) return res.sendStatus(401);
4
5  const session = await db.sessions.getByPspOrderId(evt.orderId);
6  if (!session) return res.sendStatus(404);
7  if (session.status === 'RESOLVED') return res.sendStatus(200); // 重送保護
8
9  if (evt.status === 'PAID' && evt.amount === session.amount) {
10    await shopifyGraphQL(session.shop, `
11      mutation Resolve($id: ID!) {
12        paymentSessionResolve(id: $id) {
13          paymentSession { id status { code } }
14          userErrors { field message }
15        }
16      }`, { id: session.shopifyGid });
17
18    await db.sessions.update(session.shopifySessionId, { status: 'RESOLVED' });
19  }
20
21  if (evt.status === 'EXPIRED' || evt.status === 'FAILED') {
22    await shopifyGraphQL(session.shop, `
23      mutation Reject($id: ID!, $reason: PaymentSessionRejectionReasonInput!) {
24        paymentSessionReject(id: $id, reason: $reason) {
25          paymentSession { id status { code } }
26          userErrors { field message }
27        }
28      }`, {
29      id: session.shopifyGid,
30      reason: { code: 'PROCESSING_ERROR', merchantMessage: evt.status },
31    });
32  }
33
34  res.sendStatus(200);
35});

1app.post('/fps/refunds', async (req, res) => {
2  const r = JSON.parse(req.body.toString('utf8'));
3  const payout = await psp.createFpsPayout({
4    originalOrderId: r.payment_id,
5    amount: r.amount,
6    idempotencyKey: r.id,
7  });
8  // 非同步：PSP 完成出金後再 resolve
9  await db.refunds.put({ id: r.id, gid: r.gid, payoutId: payout.id });
10  return res.sendStatus(201);
11});

1// extensions/payment-rules/src/run.js
2export function run(input) {
3  const fps = input.paymentMethods.find(m => m.name.includes('轉數快'));
4  if (!fps) return { operations: [] };
5
6  const total = parseFloat(input.cart.cost.totalAmount.amount);
7  const currency = input.cart.cost.totalAmount.currencyCode;
8
9  if (currency !== 'HKD' || total > 50000) {
10    return { operations: [{ hide: { paymentMethodId: fps.id } }] };
11  }
12  return { operations: [] };
13}

1shopify app function build
2shopify app deploy