Files
esun3d/app/code/Esun/Oceanpayment/README_CN.md
T
2026-09-15 10:35:56 +08:00

4.2 KiB
Raw Blame History

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 加密后端,日志不记录密钥。

安装

php bin/magento module:enable Esun_Oceanpayment
php bin/magento setup:upgrade
php bin/magento cache:flush

生产模式还应执行:

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。 沙盒地址固定为:

https://test-secure.oceanpayment.com/gateway/service/sendTrade

生产地址固定为:

https://secure.oceanpayment.com/gateway/service/sendTrade

推荐在 Magento 后台填写四项凭据。模块使用 Magento 的加密配置后端保存它们,不要把明文写入 Git、config.xml、部署脚本或工单。只有在执行 app:config:dump、敏感路径已经登记到 app/etc/config.php 后,才使用 config:sensitive:set 注入部署环境变量;否则该命令不会识别这些路径。

非敏感开关可以通过 CLI 设置:

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 地址,无需在源码中配置:

同步返回: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. 重放相同异步通知不会重复开票。

单元测试:

vendor/bin/phpunit app/code/Esun/Oceanpayment/Test/Unit

协议依据:Oceanpayment V4 Hosted Checkout、Parameters、Signature、Payment Status 与 Payments Webhook 文档。