# Esun_Oceanpayment Magento 2.4 钱海(Oceanpayment)支付模块,同时提供两个独立支付方式:Hosted Checkout 与 OnePage(Embedded)Checkout。客户可在 Magento 结账页直接选择跳转式付款或内嵌卡支付。 ## 功能 - 沙盒/生产环境切换; - Hosted Checkout(商户控制重定向); - OnePage Checkout(钱海官方 iframe SDK,卡号/CVV 不经过 Magento); - SHA-256 请求签名、建单响应验签和支付回调验签; - 支持同步 `backUrl` 与异步 `noticeUrl`; - 回调幂等处理,避免重复开票; - 支付成功自动生成已付款发票和 Magento 支付交易; - 成功、失败、待确认状态可配置; - 敏感配置使用 Magento 加密后端,日志不记录密钥。 ## 安装 ```bash php bin/magento module:enable Esun_Oceanpayment php bin/magento setup:upgrade php bin/magento cache:flush ``` 生产模式还应执行: ```bash php bin/magento setup:di:compile php bin/magento setup:static-content:deploy -f ``` ## 配置 后台路径:`Stores > Configuration > Sales > Payment Methods`,包含两个独立配置组: - `钱海支付 - Hosted`:下单后跳转钱海托管支付页; - `钱海支付 - OnePage`:卡支付框内嵌在 Magento checkout。 两种方式可分别启用、命名和排序,并分别保存终端配置。Hosted 必填 `Account`、`Terminal`、 `Secure Code`;OnePage 还必须填写 `Key`,且 `methods` 应为钱海已开通的 `Credit Card`。 沙盒地址固定为: ```text https://test-secure.oceanpayment.com/gateway/service/sendTrade ``` 生产地址固定为: ```text https://secure.oceanpayment.com/gateway/service/sendTrade ``` 推荐在 Magento 后台填写四项凭据。模块使用 Magento 的加密配置后端保存它们,不要把明文写入 Git、`config.xml`、部署脚本或工单。只有在执行 `app:config:dump`、敏感路径已经登记到 `app/etc/config.php` 后,才使用 `config:sensitive:set` 注入部署环境变量;否则该命令不会识别这些路径。 非敏感开关可以通过 CLI 设置: ```bash php bin/magento config:set payment/esun_oceanpayment/sandbox 1 php bin/magento config:set payment/esun_oceanpayment/active 1 php bin/magento config:set payment/esun_oceanpayment_onepage/sandbox 1 php bin/magento config:set payment/esun_oceanpayment_onepage/active 1 ``` ## 回调地址 模块会为每笔订单自动提交以下 HTTPS 地址,无需在源码中配置: ```text 同步返回:https://你的域名/oceanpayment/payment/back 异步通知:https://你的域名/oceanpayment/payment/notify ``` 为保证旧模块创建的在途订单仍可接收通知,新模块同时兼容旧的 `/paymentqianhai/payment/back` 和 `/paymentqianhai/payment/notify` 地址。 请确保上述路径可被公网访问,并且 CDN/WAF 不会拦截钱海的 POST 或 XML 请求。异步通知处理成功后返回 `receive-ok`;签名或订单校验失败时返回 HTTP 400,便于钱海按重试策略再次通知。 ## 安全说明 - `secureCode` 只在服务器端用于 SHA-256,永远不会输出到结账页; - OnePage 的 `signValue` 由服务器生成,使用文档规定的不含 `backUrl` 的字段顺序; - OnePage 官方协议要求将 `key` 随单次支付请求交给 SDK,因此仅在下单后的会话绑定接口返回; - 官方 SDK 仅从 `secure.oceanpayment.com` 加载,并通过钱海 iframe 采集卡资料; - 支付跳转地址只接受 HTTPS 且域名必须是 `oceanpayment.com` 或其子域名; - 浏览器返回不能绕过验签;异步通知作为最终支付状态来源; - 模块不会记录卡号全文、`secureCode`、`key` 或签名明文。 ## 测试 先在沙盒终端开通对应的 `methods`(默认 `Credit Card`),再用钱海文档提供的测试卡完成完整流程: 1. Magento 下单后跳转至钱海测试域名; 2. 支付成功后返回 Magento 成功页; 3. 订单变为配置的成功状态; 4. 订单中只生成一张已付款发票和一个支付交易; 5. 重放相同异步通知不会重复开票。 单元测试: ```bash vendor/bin/phpunit app/code/Esun/Oceanpayment/Test/Unit ``` 协议依据:Oceanpayment V4 Hosted Checkout、Parameters、Signature、Payment Status 与 Payments Webhook 文档。