integrate-jazzcash

集成 JazzCash

使用商户当前已获批准的 JazzCash 文档。仅将公开示例作为参考，因为不同商户和环境启用的产品、版本、字段、端点及认证要求可能有所不同。

更改前检查

在代码库中搜索 JazzCash 程序包、插件、SDK、支付表单、pp_ 字段、商户 ID、密码、完整性盐值、安全哈希构造器、沙盒／生产环境 URL、返回或回调路由、状态／退款逻辑、交易表、对账任务、测试和部署密钥。

• 如果已接入 JazzCash，请确认其集成模式、API／文档版本、环境、已启用的支付方式、哈希规则、订单生命周期及故障情况。说明最安全的升级路径，并保留现有可用或已通过认证的行为。
• 如果尚未接入，请依据该商户提供的最新文档，使用项目当前技术栈设计集成。
• 切勿猜测或照搬端点 URL、凭证名称、签名字段、字段顺序、编码、算法、响应代码或状态含义。请根据商户门户、当前指南和测试向量进行确认。

确认产品

当前公开的 JazzCash 沙盒文档标注为 v4.2，介绍了 HTTP POST 页面重定向和 API 测试。其公开功能页面介绍了移动钱包、代金券、银行卡、托管／重定向等网关功能。请确认商户实际获批使用的功能。

不要将在线支付网关与个人钱包转账、商业 QR／Raast QR、支付链接、批量支付、零售代理服务或其他 JazzCash 企业 API 混淆。实施前请确认所需产品。

工作流程

1. 获取最新的商户指南、所选集成模式、已启用的支付方式、沙盒凭证、返回／回调规则、哈希示例、状态／退款操作、响应代码表、认证用例、结算条款及生产环境资料包。
2. 记录准确的文档、插件或 API 版本。编辑前，将其与现有实现进行比较。
3. 在服务端创建待处理订单，并分配唯一的商户交易／参考 ID。
4. 在服务端计算商品、金额、币种、折扣、配送费、有效期及客户所有权。
5. 严格按文档构建并计算最终请求的哈希。将商户密码、完整性盐值、密钥和证书保留在服务端。
6. 让客户通过获批的托管、重定向、钱包、代金券或银行卡流程完成支付。除非合同约定且符合 PCI 要求的方法明确允许，否则切勿收集 JazzCash MPIN、OTP 或银行卡详细信息。
7. 浏览器返回仅用于展示。对服务端通知进行身份验证和去重，验证订单及金额，并通过获批的状态查询源核实结果不明确的交易。
8. 仅在收到权威的成功结果后履行订单一次。保存网关交易、响应、支付方式、撤销／退款及结算标识符。
9. 处理取消、拒付、过期、超时、响应丢失、重复／延迟回调、撤销／退款及结算不匹配。
10. 通过沙盒和商户认证测试后，再申请启用生产环境。

不可妥协的规则

• 绝不在前端代码、移动端二进制文件、代码仓库、日志、URL、屏幕截图或错误信息中暴露凭据或完整性材料。
• 绝不单凭重定向、查询参数、客户端响应、短信或屏幕截图将订单标记为已付款。
• 严格按照指定方式实现规范化和安全哈希验证；在适用时使用时序安全的摘要比较。
• 确保内部订单引用和 JazzCash 交易标识符唯一。支付状态转换和订单履约必须具备幂等性。
• 在通过状态验证或对账确认结果之前，将超时视为状态未知。绝不盲目发起第二笔扣款。
• 使用整数最小货币单位或指南规定的精确金额格式；绝不使用二进制浮点数。
• 未经明确批准，绝不执行真实支付、扣款、退款、冲正或凭据变更。

参考资料路由

• 阅读 references/integration-workflow.md，了解模式、订单状态、请求处理、回调、状态恢复、插件和测试。
• 实现哈希、密钥、幂等性、监控、对账或上线控制之前，请阅读 references/security-and-operations.md。
• 阅读 references/research-notes.md，了解注明日期的来源以及必须重新核实的详情。

验证并报告

运行项目的格式化工具、静态检查／类型检查、测试和构建。报告 JazzCash 是原本已有还是从头添加；指南／API／插件版本；已启用的方法；已实现的流程；回调和哈希验证；幂等性；未知状态恢复；对账；认证状态；以及剩余的商户门户配置。将公开研究、商户规范、沙盒证据和线上环境批准情况分别说明。