Files
2026-09-15 10:35:56 +08:00

109 lines
4.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 文档。