SuperAPI AI 工具集

setup-payright

编程与开发

查看项目

更新于 11-17 02:10

技能介绍

用途\n该技能面向 Payright(Payright Sdn Bhd,吉隆坡)支付网关的集成开发工作,可用于搭建、编写、调试、审查和解释相关集成代码与方案。参考资料涵盖端点目录、基础 URL、认证头、Collection 与 Bill 请求/响应字段、JWT 回调格式与解码规则、Get Bill 查单、请求签名(X-Signature)、出款与余额接口、错误码、支付渠道 ID,以及文档中已记录的缺口。\n\n主要能力\n- 区分环境与接口面:沙箱(https://api.payright-sandbox.my/api/v1)或生产(https://api.payright.my/api/v1);Bill API(FPX 收银台)、Payout API(出款)或无代码方式(支付表单、门户账单、插件)。\n- 账单流程指导:先用自有唯一 invoice_ref 在本地创建待支付记录,再调用 POST /merchant/list-payment-provider 获取渠道并让付款人选择银行,随后在服务端 POST /merchant/bills 创建账单(必填 collection_uuid、amount 以 MYR 两位小数、provider_id、callback_url、redirect_url、full_name、email、phone_number),保存 invoice_no 并跳转 payment_url。\n- 回调处理:回调体为 JSON,含 data(使用 Hash Key 以 HS256 签名的 JWT)与 response_code;须固定 HS256 验签,校验失败一律拒绝。按 invoice_ref(而非回调中的 FPX 发票号)与金额匹配,invoice_status 为 SUCCESS 后再幂等结算,并用 GET /merchant/bills/{invoice_ref} 复核。\n- 查单兜底:Get Bill 支持按 invoice_no 或 invoice_ref 查询,返回 transaction_details.status 与 fpx_invoice_no;文档仅承诺成功交易会回调,因此需用查单覆盖缺失回调。\n- 请求签名:门户开启 JWT Verification 后,每个请求需携带由 Hash Key 以 HS256 签发的 x-signature,载荷含 auth-token、http_method、url_path、iat、exp。\n- 出款与余额:POST /merchant/payout、查询出款、list-payout-providers、GET /merchant/balance;相同金额、账号与收款人引用在 3 小时内重复会返回错误 10149。\n\n使用方式\n给出 API 结论或写代码前先读 references/payright-api.md;涉及注册、密钥位置、沙箱与生产、环境变量、JWT 校验开关、支付方式、结算或价格时读 references/account-setup.md;需要选择对应官方页面或识别未文档化区域、避免参考 2022 年旧插件时读 references/source-map.md。工作流强调:确认门户配置(Auth Token、Hash Key、JWT Verification 开关、collection_uuid、已激活的支付服务)→ 本地待支付记录 → 获取渠道 → 服务端建单 → 验签回调 → 幂等结算 → 查单复核。\n\n适用场景\n马来西亚市场的 FPX 收银台接入、支付回调安全审查、对账与查单任务设计、出款接口接入、集成代码评审与问题排查。\n\n限制与注意\nAuth Token 与 Hash Key 只能保存在服务端,不得下发到浏览器或移动端;不得依据 redirect_url 或任何浏览器查询参数判定支付成功;不得接受 alg: none 或不验签直接解码;金额以两位小数林吉特表示(非分);响应信封中的业务错误可能以 HTTP 200 返回,需检查 status 与 code;每次尝试需生成新的 invoice_ref,复用会返回 425;不得参考 2022 年 GitHub 插件(其针对已停用 API);不要与澳大利亚 Payright(BNPL)混淆。文档未覆盖退款、PENDING/SUCCESS 之外的状态枚举、回调重试、重定向参数、限流、IP 白名单以及回调 exp/iat 等,相关结论需明确标注为暂未提供。