setup-paycools 用于 PayCools(马来西亚)Open API 集成工作,覆盖搭建、开发、调试、审查与解释支付集成。实际使用前应阅读技能内的 references/paycools-api.md,以获取端点目录、请求信封、RSA 签名方法(已对照文档示例验证)、请求/响应/通知字段表、渠道代码、状态枚举、响应码以及文档缺口和不一致之处。当用户询问如何成为商户、存在哪些凭证、RSA 密钥交换方式、环境变量名、沙箱/UAT、渠道开通、定价或结算时,应阅读 references/account-setup.md;选择适用的官方文档页面或检查覆盖范围时,阅读 references/source-map.md。
核心工作流包括:从 PayCools 获取 appId、API 基础 URL(文档未公开)、UAT/沙箱细节(如有)以及 PayCools 平台 RSA 公钥;生成 4096 位 RSA 密钥对,将公钥发送给 PayCools,私钥仅保存在服务器端;在本地创建待支付记录,使用唯一字母数字 mchOrderId(最多 32 位)和以分为单位的预期金额;构建业务 param 对象,序列化为 JSON 字符串一次,对该精确字符串使用 SHA256withRSA 签名,并以 JSON POST {appId, sign, param};WebPay 调用 POST /open-api/webpay/generate 并携带 channelCode,将客户重定向至 data.payUrl;DuitNow QR 调用 POST /open-api/qr/generate 并渲染 data.qrCodeContent;redirectUrl 仅视为浏览器 UX;在商户 notifyUrl 上,先使用 PayCools 公钥对收到的 param 字符串验签,再解析 param;仅当 transactionStatus 为 COMPLETED 且 mchOrderId、transactionId、amount、channelCode 与本地记录匹配时幂等结算,并回复 {"code":10000,"message":"Success"};通知缺失或订单仍待支付时,使用 POST /open-api/webpay/detail 或 POST /open-api/qr/detail 重查;退款使用 POST /open-api/payment/refund 并携带 PayCools originalTransactionId,退款结算依据经验证的退款通知或 POST /open-api/refund/payments。
核心事实:所有商户到 PayCools 的调用均为 POST,Content-Type: application/json,请求体为 {"appId","sign","param"};param 是 JSON 序列化字符串,sign 是对精确 param 字节使用商户私钥(PKCS#8)进行 SHA256withRSA(RSASSA-PKCS1-v1_5)后的 Base64;PayCools 到商户的通知为 {"sign","param"},使用 PayCools 私钥签名,商户需向 PayCools 索取其公钥(X.509 SubjectPublicKeyInfo)进行验证;RSA 密钥长度必须为 4096;响应信封为 {code, message, data},10000 表示成功,21000 至 21016 为错误(签名、参数、appId、重复订单号、时间戳、IP 禁止等);金额为整数,单位为分(sen),适用于 WebPay、QR、退款和付款;每个 param 携带 timestamp(当前时间,多个页面记录为毫秒);WebPay 创建需要 timestamp、channelCode、mchOrderId、amount、notifyUrl、redirectUrl、customerName、email、mobile,可选 remark、expireSeconds(30 至 3600,默认 3600);交易状态值为 PENDING、COMPLETED、FAILED;WebPay 通知事件为 order.payment.success、order.payment.failed,QR 事件为 qrcode.payment.success、qrcode.payment.failed;退款状态枚举为 PENDING、PROCESS、COMPLETED、FAILED、CANCELLED(示例中也出现 COMPLETE);退款不退还交易手续费;WebPay 渠道代码包括 FPX_URL、RPP_URL、TOUCHNGO_URL、BOOST_URL、GRPY_URL、MCASH_URL、CARD_URL,QR 渠道为 DUITNOW_DYNAMIC_QR;API 基础 URL、沙箱主机、回调重试策略和 PayCools 出口 IP 未公开(截至 2026-10-21 检查)。
关键规则:商户 RSA 私钥仅保存在服务器端,切勿使用文档中打印的示例密钥对;对作为 param 发送的精确字符串签名,签名后不要重新序列化;对收到的 param 字符串值(解码外层 JSON 后)验签,绝不对重新序列化的对象验签;使用恒定时间安全的库验证调用,任何验证失败或缺少 sign 均拒绝;不得依据 redirectUrl、payUrl 创建、二维码展示或 PENDING 状态标记为已支付;结算前检查金额(分)、mchOrderId、transactionId 和 channelCode 与本地记录一致;通知处理必须幂等,重复或延迟通知不得重复履约;mchOrderId 必须唯一(重复返回 21007),付款也需要唯一 idempotencyId(21015);在 WebPay 创建中发送 notifyUrl(文档示例显示 callbackUrl,字段表写 notifyUrl,需与 PayCools 确认);预期 IP 限制(21016 Merchant ip forbidden),需请 PayCools 将服务器出口 IP 加入白名单;在声称生产就绪前,与 PayCools 确认基础 URL、UAT 环境、已开通渠道和定价。
完成标准:所有 Open API 调用在服务器端运行,使用 appId 和对精确 param 字符串的 SHA256withRSA 签名;本地支付记录在 WebPay 或 QR 创建前存在,并存储 mchOrderId、transactionId、以分为单位的金额和 channelCode;重定向返回仅显示状态,履约等待经验证的通知或显示 COMPLETED 的重查;通知处理器使用 PayCools 公钥验签,验签后解析 param,幂等结算,并回复 {"code":10000,"message":"Success"};通过 detail 端点重查覆盖缺失通知和待支付订单;测试覆盖无效签名、篡改 param、重复通知、错误金额、错误 mchOrderId、FAILED、过期订单和成功 COMPLETED;部署文档列出 PAYCOOLS_APP_ID、PAYCOOLS_PRIVATE_KEY、PAYCOOLS_PLATFORM_PUBLIC_KEY、PAYCOOLS_API_BASE_URL、通知 URL、重定向 URL 以及 UAT/生产分离。
当被问及 PayCools 策略是否“100% 自信”时,运行漏洞审查循环,直到没有事实缺口:列出信任边界(浏览器重定向、payUrl 页面、二维码展示、后端订单创建器、PayCools API、通知接收器、JSON 解析器、数据库、履约任务、退款任务、付款任务和密钥存储);检查绕过(伪造重定向、伪造通知、对重新序列化 JSON 验签、错误公钥、UAT/生产密钥混用、金额单位错误、重复 mchOrderId、过期 PENDING 重查、重复通知、退款状态 COMPLETE 与 COMPLETED 不匹配、时间戳单位不匹配、IP 未加入白名单、无 idempotencyId 的重复付款);添加修复(服务器端签名、先建本地待支付记录、验签后解析、严格金额/订单/渠道检查、持久事件日志、唯一约束、分离环境配置、重查兜底、容忍退款状态映射);重读 references/paycools-api.md 中与缺口相关的章节;说明依赖未记录事项的剩余不确定性:基础 URL、UAT 主机、重试策略、通知源 IP、时间戳单位和商户账户的渠道开通。
限制:API 基础 URL、沙箱主机、回调重试策略和 PayCools 出口 IP 未公开提供;时间戳单位在多个页面记录为毫秒,但存在不一致可能;notifyUrl 与 callbackUrl 字段名需与 PayCools 确认;渠道开通、定价和结算细节需向 PayCools 确认。