用途
该技能面向 senangPay 支付网关的集成工作，可用于搭建、构建、调试、审查和讲解 senangPay 支付集成。它要求先阅读 references/senangpay-api.md 再给出 API 指导或编写集成代码，该文件包含来源 URL、集成面、环境 URL、端点角色、参数规则、哈希公式、回调行为、查询 API、Direct API、FPX 银行列表、退款 API 以及结算与安全注意事项。涉及注册、凭证来源、沙箱设置、仪表盘设置、套餐能力、定价、支持或迁移背景时，应阅读 references/account-setup.md；选择托管结账、Direct API、插件、回调、查询 API、退款、循环支付、令牌化、分账结算、打款、沙箱或迁移对应的指南页面时，应阅读 references/source-map.md。
主要能力
技能覆盖的核心工作流包括：识别环境（沙箱或生产）；识别集成面（托管/手动支付表单、购物车插件、电商平台集成、Direct API、循环支付、退款 API、打款 API、令牌化或分账结算）；确认凭证与仪表盘设置（Merchant ID、Secret Key、Hash Type、Return URL、Callback URL）；在将客户送往 senangPay 之前创建本地待处理支付；使用正确公式和账户 Hash Type 在服务端生成请求哈希；在服务端重定向到托管结账或创建 Direct API 客户端会话；将 Return URL 仅视为浏览器用户体验，不单独据此履约；在服务端验证回调/返回哈希，必要时重新查询订单或交易状态，仅在金额、订单 ID、状态、商户、环境和提供商交易参考均匹配后才结算；并使结算具备幂等性，因为 senangPay 可能发送多次回调，且后续回调可能取代先前状态。
使用方式与核心事实
生产托管结账 URL 为 https://app.senangpay.my/payment/{merchant_id}，沙箱托管结账 URL 为 https://sandbox.senangpay.my/payment/{merchant_id}。托管/手动结账接受 GET 或 POST 参数，金额使用两位小数，例如 25.50；Direct API 金额使用分，例如 200 表示 RM 2.00。手动请求哈希源序列为 {secret_key}{detail}{amount}{order_id}。返回/回调状态值：1 成功、0 失败、2 待授权。返回/回调验证源序列为 {secret_key}{status_id}{order_id}{transaction_id}{msg}。查询订单状态端点为 GET https://app.senangpay.my/apiv1/query_order_status，查询交易状态端点为 GET https://app.senangpay.my/apiv1/query_transaction_status。Direct API 端点为 POST https://api.senangpay.my/payment/v3 和 POST https://api.sandbox.senangpay.my/payment/v3，需要 Enterprise 套餐、已授权商户访问以及出站服务器 IP 白名单。Merchant ID 和 Secret Key 位于 Dashboard > Settings > Profile > Shopping Cart Integration Link。推荐 SHA256，MD5 为遗留/已弃用，仅用于明确要求它的系统。Callback URL 使用 HTTP POST，成功接收时必须输出恰好 OK，不带 HTML 标签。
适用场景
适用于需要接入 senangPay 的托管结账、Direct API、插件、回调处理、查询、退款、循环支付、令牌化、分账结算、打款、沙箱或迁移等场景，也适用于对现有 senangPay 集成进行安全审查与漏洞排查。
限制与关键规则
Secret Key 和私有哈希输入必须仅保留在服务端。不得仅凭 Return URL、前端事件、SDK 响应或浏览器重定向标记已付款。优先使用 SHA256/HMAC-SHA256，除非支持明确的遗留集成，否则避免 MD5。始终按当前流程文档记载的精确序列验证哈希。在标记已付款前，验证本地订单、预期金额、状态、交易 ID/参考、商户 ID 和环境。持久记录回调事件，并在返回 OK 前使处理具备幂等性。预期同一交易会出现重复回调，也预期在后续成功回调之前出现待处理或失败回调，最新回调可能是最新状态。避免回调重定向和依赖会话的回调处理器。分离沙箱与生产凭证、URL、回调 URL、Return URL 和仪表盘设置。对于 Direct API，绝不在浏览器 JavaScript 中暴露 Secret Key，并注意 UUID 仅 60 秒有效。对于退款 API，存储本地退款尝试，在重复、部分退款、退款窗口或金额超限错误后不要盲目重试。若涉及套餐能力、支付方式可用性、结算时间、当前定价、IP 白名单、迁移行为或仪表盘状态，需在声称确定前核实实时 senangPay 仪表盘/文档/支持。
当被问及某 senangPay 策略是否“100% 确信”时，技能要求运行漏洞审查循环：列出信任边界（浏览器 Return URL、后端结账创建器、senangPay 托管结账、Direct API 会话端点、JavaScript SDK、回调接收器、查询 API、数据库、履约任务、退款任务、仪表盘设置、套餐/渠道激活）；检查绕过（伪造成功返回、伪造回调、错误哈希类型、错误哈希序列、错误金额格式、错误订单 ID、错误商户 ID、沙箱/生产混用、重复回调、失败回调后成功、待处理标记为已付款、过期 Direct API UUID、Direct API Secret Key 泄露、未白名单的 Direct API 服务器 IP、未激活 FPX 银行、重复退款请求、不支持部分退款、180 天窗口后退款）；添加修复（服务端本地待处理支付、服务端哈希生成、回调哈希验证、状态复查、严格金额/状态/订单检查、幂等键、回调事件日志、持久记录后精确 OK 响应、环境分离配置、银行状态过滤、套餐能力检查、退款幂等性）；重新阅读 references/senangpay-api.md 中与任何缺口相关的章节；若剩余不确定性取决于当前套餐、渠道启用、定价、仪表盘配置、DOKU 迁移状态或 senangPay 支持审批，则说明该不确定性。