用途
该技能面向 FavePay Omni(FPO)支付网关的集成工作,可用于搭建、调试、审查和解释 FavePay(Fave / FaveBiz)支付集成。资料要求在进行事实性 API 指导或编写集成代码前,先阅读 references/favepay-api.md;在涉及注册、凭据、沙箱 UAT 与签核、环境变量名、支付方式、插件、定价或结算时,阅读 references/account-setup.md;在选择官方页面或插件文件支撑某个事实时,阅读 references/source-map.md。
主要能力
- 区分环境:沙箱为 https://omni.dino.fave.ninja,生产为 https://omni.myfave.com,两套凭据相互独立。
- 区分国家路径段:my 对应 MYR,sg 对应 SGD;货币跟随路径,没有货币字段。
- 识别流程:在线结账(format=web_url)、店内动态 QR(txt、base64、favepay)、钱包 QR(grab、alipay、wcp、shopeepay、atome、paynow)、商户扫码或静态 QR(计划中)。
- 调用 Fave 前先在本地创建待处理支付,并使用唯一 omni_reference(<Fave 前缀>-<id>,最多 28 字符)。
- 在服务端向 /api/fpo/v1/<cc>/qr_codes 发起 POST,携带 total_amount_cents、app_id、outlet_id、format、redirect_url、callback_url,并将 sign 放在最后。
- 对 web_url 流程,将客户重定向到返回的 code;对 QR 流程,渲染 QR 载荷或图片。
- Webhook 处理:按收到的字段与收到的顺序验签,快速返回 HTTP 2XX,并幂等处理。
- Webhook 延迟或缺失时,通过 GET /api/fpo/v1/<cc>/transactions(按 omni_reference 或 receipt_id)确认。
- 未支付的 QR 通过 POST .../transactions/cancel 取消;已支付的通过 POST .../transactions 且 status=refunded 退款(默认同日)。
使用方式与关键规则
认证依赖 sign 字段:对按发送顺序排列的 URL 编码字段计算 HMAC-SHA256,以小写十六进制表示,密钥为 Fave secret key。签名时始终排除 sign 与 country_code;同时排除路径 outlet_id(list)、路径 id(acknowledge)与 details(merchant scan)。不要对键排序;嵌套对象展平为方括号形式,例如 shopper_details[email]=...。金额为整数分(total_amount_cents),多数响应金额为字符串。
编码方式应与 PHP urlencode / http_build_query 一致:空格转为 +,除 A-Z a-z 0-9 - _ . 之外的字符做百分号编码(大写十六进制)。Webhook 验签需使用保留顺序的解析器,按收到 JSON 键的原始顺序计算,并使用常量时间比较。不得仅凭重定向标记支付成功,只有在验证过的 Webhook 或签名 GET /transactions 返回 successful 后才可标记。结算前核对 omni_reference、total_amount_cents、currency、outlet_id 与状态,并以 receipt_id 或 id 为键幂等结算。同一订单每次生成新 QR 都要使用新的 omni_reference。沙箱密钥只能配沙箱基础 URL;UAT 签核后 Fave 会签发新的生产密钥。静态 QR 使用前需与 Fave 确认可用性,文档标记为计划中。
创建响应包含 code、format、expires_in(秒),默认 format 为 base64。Webhook 状态为 successful 与 rejected;过期或取消的未支付 QR 可能发送 rejected。status_code:0 pending_payment、1 payment_processing、2 successful、3 disputed、4 rejected、5 refunded。交易 id 前缀包括 FP_(FavePay)、RPP_(DuitNow)、GRAB_、PAYNOW_、EXT_(其他钱包)。Fave 对非 2XX 的 Webhook 按递增间隔重试,同一支付可能多次到达。创建时 test=true(仅沙箱)会在 code 中返回测试页 URL 以模拟成功或失败,切勿用于生产。错误使用 error 与 error_description:签名错误为 401;未知 app_id 为 404 resource_not_found;重复 omni_reference 为 400 validation。退款窗口默认同日(超出返回 stale_transaction);DuitNow 或 PayNow 不支持部分退款。
完成标准
集成完成的判断条件包括:服务端以正确签名创建 QR 或 web_url 并返回 code;重定向页仅展示状态,或在展示成功前服务端重新查询交易;Webhook URL 已按环境注册给 Fave(启动会议)或作为 callback_url 传入;Webhook 处理器验签、快速返回 2XX,且每笔支付只结算一次;结算核对参考号、金额、货币、门店与 successful 状态;定时重查处理漏掉的 Webhook,静态 QR 流程调用 Acknowledge;测试覆盖签名错误、重复 Webhook、金额错误、rejected、过期 QR、取消、全额退款与 stale_transaction;在申请生产密钥前通过沙箱 UAT 清单(A1 至 A4、B1 至 B2、C1、D1 至 D3)。
适用场景与限制
适用于 FavePay Omni 的在线结账、店内动态 QR、钱包 QR 及商户扫码集成,也适用于对现有集成做安全审查与“是否 100% 确信”的漏洞复核(信任边界、绕过路径、修复措施)。资料未提供费率、定价、结算时间、限流、Webhook 来源 IP、omni_ref 的 IV 与填充、签名中布尔与 null 的编码方式、重试计划等事实,这些内容暂未提供,需以官方文档或 Fave 确认为准。静态 QR 标记为计划中,使用前必须与 Fave 确认。