用途
setup-fasspay 用于 Fasspay(Fass Payment Solutions,Soft Space 集团旗下)支付集成工作,包括搭建、构建、调试、审查与解释。
资料覆盖范围
- 在线结账:需先阅读 references/fasspay-api.md,其中包含端点目录、环境、请求签名、创建支付字段、回调格式与校验、状态码、重新查询、void、capture 及已知缺口。该文件事实来自 Fasspay 在 WordPress.org 发布的官方 WooCommerce 插件源码(v1.0.14),因为 Fasspay 未公开电商 API 文档。
- 线下场景:references/fasspay-in-person.md 涵盖 Fasstap SDK(手机拍卡)、Fasstap App-to-App、Smart Terminal SDK 以及 developers.softspace.com.my 的开通 Web API;字段表见 references/fasspay-fasstap-sdk.md、references/fasspay-app-to-app.md、references/fasspay-smart-terminal.md,错误码见 references/fasspay-fasstap-codes.md。
- 账户:references/account-setup.md 涵盖注册、凭据、UAT 与生产、支付方式开通、结算与定价链接。
- 选页:references/source-map.md 用于选择正确的官方页面并查看覆盖情况。
核心工作流
- 识别场景:在线结账(电商 API)、Fasstap SDK、Fasstap App-to-App 或 Smart Terminal。
- 识别环境:UAT https://wallet-uat.fasspay.com 或生产 https://ecom.fasspay.com。
- 确认 Fasspay 提供的凭据:该环境对应的 Merchant ID(mid)与共享 Secret Key。
- 本地创建待支付记录,每次尝试使用唯一 trxRefNo,金额以 sen 计,货币 MYR。
- 服务端调用 POST /v3/ecom/webInitiateRequest,携带 messages 信封、X-Timestamp 与 X-Signature。
- 从响应 messages 字段的 JSON 字符串中读取 paymentURL,并将客户重定向至该地址。
- responsePageURL 仅作浏览器体验用途,绝不可据此标记已支付。
- 在 backendURL 回调中,先对原始 body 加 X-Timestamp 校验 X-Signature,强制 300 秒时间窗,再解析。
- 仅在 trxRefNo、金额、货币与环境均匹配后,对 statusId 100、104(或旧版 00)做幂等结算。
- 回调缺失或不清晰时,使用 POST /v3/ecom/checkTransactionStatus 作为兜底。
核心事实
- 生产 API 基址 https://ecom.fasspay.com,UAT 基址 https://wallet-uat.fasspay.com。
- 所有电商调用均为 HTTPS 下 /v3/ecom/ 的 POST JSON。
- 签名:X-Signature = base64(HMAC-SHA256(secretKey, bodyJson + X-Timestamp)),请求头 X-Signature-Alg: HmacSHA256,X-Timestamp 为 Unix 秒。
- secret 作为字面字符串密钥使用,不做 base64 解码。
- 对实际发送的字节签名;插件使用 json_encode(..., JSON_UNESCAPED_SLASHES)。
- 创建支付将字段包在 {"messages": "<JSON string>", "sandboxMode": <bool>} 中。
- amount 为以 sen 计的整数(RM 1.00 为 100)。插件仅接受 MYR。
- 回调头:X-Signature(或 X-Fasspay-Signature)与 X-Timestamp;body 可能为 {"messages": "<JSON string>"}。
- 已支付状态:100 APPROVED、104 SETTLED、旧版 00。失败:102 DECLINED、旧版 02。撤销/取消:107、旧版 03。退款:06。
- 待处理状态:101 PROCESSING、106 OPENED(银行侧待处理)、111 PROCESSING_VOID、123 PROCESSING_CAPTURE、115 PENDING_APPROVAL(FPX B2B)、122 AUTHORIZED(预授权)。
- 回调中的 transactionMethod:0 FPX、5 卡、34 电子钱包、35 DuitNow QR。
- Void:POST /v3/ecom/auth/void;成功为 statusId 107;插件阻止 FPX 的 void 以及订单日历日之后的 void。
- 未记录公开的退款发起端点;退款以回调状态 06 到达。
- 线下场景的 statusId/响应码与电商码不同(例如 Fasstap 中 102 为 VOIDED)。不同场景不可共用同一状态映射。
- 官方插件内嵌公开 UAT 凭据(值见 references/account-setup.md,仅沙箱使用);生产 MID 与 secret 由 Fasspay 在开通时提供。
关键规则
- Secret Key 仅保存在服务端。绝不从浏览器或移动客户端调用电商 API。
- 在 JSON 解析前,对原始请求体校验回调签名,使用常量时间比较。
- 拒绝 X-Timestamp 与服务器时间相差超过 300 秒的回调;拒绝缺失签名的回调。
- 自行核对金额、货币、trxRefNo 与环境。官方插件不比较回调金额与订单总额。
- 每次尝试生成新的 trxRefNo 并存储;忽略被取代尝试的非资金回调。
- 对已支付订单再次收到资金变动回调(00、100、104、122)时,视为重复支付,需人工退款或撤销。
- 绝不让迟到的失败回调(02、102)撤销已记录的支付。
- 仅在回调被持久记录后返回 HTTP 200;签名错误返回 401,JSON 错误返回 400。
- UAT 与生产的 MID、secret、基址与 sandboxMode 作为一整套使用,不得混用。
- 不要把线下状态码复制到电商处理器中。
适用场景与完成标准
仅当以下条件满足时,Fasspay 集成才算完成:webInitiateRequest 在服务端以正确信封、X-Timestamp 与 X-Signature 运行;客户被重定向至 paymentURL,返回页不做履约;backendURL 为公网 HTTPS 并对原始 body 加时间戳验签;结算校验 trxRefNo、statusId、金额、货币、环境与尝试;重复回调、被取代尝试与状态重查均幂等;测试覆盖错误签名、过期时间戳、重复回调、金额错误、失败、待处理(101、106、115)与通过;部署文档列出 FASSPAY_MID、FASSPAY_SECRET_KEY、FASSPAY_BASE_URL、FASSPAY_SANDBOX、回调 URL 与返回 URL。
限制
资料列出仍需向 Fasspay 支持确认的不确定项:回调金额单位、checkTransactionStatus 响应结构、refundAmount 单位、请求中 transactionMethod 100 的含义、IP 白名单、速率限制等。