109 lines
4.2 KiB
Markdown
109 lines
4.2 KiB
Markdown
# 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 文档。
|