integrate-easypaisa

集成 Easypaisa

请根据商户当前获批的集成指南接入 Easypaisa 支付，不要照搬旧代码片段。Easypaisa 文档和可用支付模式可能因商户协议和环境而异。

首先：检查现有集成

检查代码库中是否存在 Easypaisa/Easypay 软件包、插件、支付网关客户端、商户/商店 ID、哈希密钥配置、环境 URL、托管结账表单、移动账户或 OTC 流程、返回/回调/后推路由、交易状态验证、冲正处理、订单字段、结算任务、测试和部署密钥。

• 如果已有集成，请确认其实现所依据的指南/版本、已启用模式、环境、签名/规范化规则、端点、订单生命周期和已知故障。逐步修复，并保留已认证的行为。
• 如果没有集成，请使用项目现有技术栈和商户最新的入驻/集成资料来设计。
• 切勿臆造或照搬凭据名称、请求字段、端点 URL、哈希顺序、算法、响应代码、状态值或回调规则。请根据当前商户文档和测试向量逐项核实。

确认产品和商户资格

Easypaisa 当前的官方资料显示，企业/实体可申请开通在线支付网关，但须拥有已上线的网站或移动应用，并通过申请、资料审核、KYC/尽职调查和集成流程。公开列出的模式包括 Easypaisa 移动账户和 OTC；列出的插件适用于 WooCommerce、OpenCart、Magento 和 PrestaShop。实际启用的模式、费用、结算、限额和技术协议均以商户协议为准。

请勿将在线支付网关与个人钱包转账、商户二维码/Till、支付链接、批量付款、银行卡收单、托管服务或定期订阅引擎混淆。编码前请确认所需的 Easypaisa 产品。

工作流

1. 获取最新的商户集成指南、沙盒/预发布环境详情、获批的支付模式、凭据、测试账户/数据、签名示例、回调规则、状态/冲正 API、认证用例、结算条款和生产切换资料。
2. 记录准确的指南/API/插件版本，并与现有代码进行对照。
3. 在发起支付前，创建内部待处理订单，并分配唯一的商户订单/参考 ID。
4. 在服务器端计算商品、数量、金额、币种、折扣、配送费用和客户归属。切勿将客户端提交的支付金额视为权威值。
5. 严格按照文档规定的字段、顺序、编码和算法生成请求及完整性校验值。签名密钥必须保留在服务器端。
6. 仅通过合同约定的托管/直连/移动账户/OTC 流程引导客户。返回 URL 和服务器通知 URL 均须使用 HTTPS。
7. 浏览器返回仅用于改善用户体验。验证并去重服务器回调/后推通知，然后通过获批的状态查询机制或商户门户确认结果不明确的交易。
8. 完成服务器端验证后再履行订单，且只履行一次。记录交易、订单、渠道、状态和结算标识符，以便支持和对账。
9. 实现失败、取消、超时、重复请求、延迟回调、冲正、受支持情况下的退款，以及结算不匹配等处理路径。
10. 使用获批用例在预发布环境中测试，并在启用正式环境前完成商户认证/审批。

不可妥协的规则

• 切勿在浏览器代码、移动应用、代码仓库、日志、屏幕截图或错误信息中暴露商户凭据或哈希／签名密钥。
• 切勿仅凭查询参数、成功页面、客户端 JSON、短信、屏幕截图或重定向就将订单标记为已付款。
• 必须按照官方规定的精确规范化方式验证消息完整性；应用在比较摘要时必须采用时序安全比较。
• 确保订单标识符和外部交易标识符唯一，并使履约操作具备幂等性。
• 将超时或响应丢失视为状态未知，而非失败，直至核实为止。
• 使用整数最小货币单位或指南要求的精确十进制格式；切勿使用二进制浮点数。
• 切勿盲目重试创建扣款／付款。
• 未经明确批准，切勿执行真实付款、冲正、退款或凭据变更。

参考资料路由

• 阅读 references/integration-workflow.md，了解订单状态、托管式／移动账户／OTC 流程、回调、验证、插件和测试。
• 在实现签名、密钥、幂等性、对账、监控或生产环境部署之前，阅读 references/security-and-operations.md。
• 阅读 references/research-notes.md，了解带日期的官方来源、当前公开声明、社区证据以及必须重新核实的详情。

验证与输出

运行相关格式化工具、静态分析／类型检查、测试和构建。报告是否找到了 Easypaisa，或是从头开始添加；所用的产品／模式和指南版本；已实现的流程、回调验证、幂等性、交易状态恢复、对账和认证状态；以及商户门户中仍需完成的配置。明确区分公开调研、商户提供的规范、暂存环境证据和生产环境批准。