=== VNPAYMENT for WooCommerce ===
Requires at least: 6.6
Requires PHP: 8.1
Requires Plugins: woocommerce
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

== Description ==
Accept ordinary channel payments and USDT through your existing VNPAYMENT merchant account. Supports classic checkout, Checkout Blocks and HPOS. Plugin-owned interface labels follow the WordPress Chinese/English locale.

== 安装与配置 ==
1. WordPress 后台 → 插件 → 安装插件 → 上传插件，选择本 ZIP，安装并启用。先启用 WooCommerce。
2. WooCommerce → 设置 → 付款 → VNPAYMENT。启用支付方式，填写商户登录账号、商户签名密钥、通道编号。
3. 网关填 https://payment.271458.xyz/ （根地址，不附 ?c=Pay）。插件自动生成 HTTPS 回调地址。
4. 普通通道：填写平台约定收款币种，必须与商店币种相同。例如 2601 的币种须先与平台确认；不自动换汇。
5. 数字货币：填写商店币种代码及固定汇率。人民币商店填 CNY、7，表示 1 USDT = 7 元；7 元订单收 1.00 USDT。美元等商店同样填写对应币种和汇率。USDT 商店使用 1:1。
6. 通道：主网 2901 Ethereum / 2902 TRON / 2903 BSC；测试网 2911 Sepolia / 2912 Nile / 2913 BSC Testnet。一次启用一个通道，修改只影响新订单。平台需预先开通通道和可用收款钱包，并有足够对应环境的 USDT 服务费余额。
7. 默认测试网确认仅保持“保留/on-hold”。仅在不发真实商品的测试店铺开启“允许测试网订单标记已付款”。人工“测试回调”永远不标记真实付款。

== 金额与状态 ==
应付 USDT = 商店订单总金额 / 插件固定汇率，四舍五入到两位；不足 0.01 USDT 或超出支持范围会拒绝下单。固定汇率最多八位小数；当前支持商店总额精确到两位小数，三位小数币种金额须先调整计价。订单保存下单汇率和金额快照，不因后续改价改汇率自动重算。此汇率仅在商户插件中换算商品价格；平台收到的数字货币订单金额和阶梯服务费均按 USDT 计算。

下单后顾客进入订单付款页，再点击打开平台收银台/二维码；本页显示确认状态。平台订单号、商户订单号、通道、交易哈希可在 WooCommerce 订单详情中查看，平台后台也会显示真实下单记录。

数字货币自动使用 v2：等待付款 → 检测到付款（保留/on-hold）→ 已确认（WooCommerce payment_complete，按商品类型为处理中/已完成）。超时为已取消；之后平台人工补单且查询确认为成功时可恢复付款。普通通道使用固定八字段 v1 验签。浏览器返回本身不构成付款凭据。

接收器对原始字段验签，核对订单、商户、金额与链资产；最终成功还会向平台查询核验。事件持久化、按订单加锁、序号防回退、重复回调去重。订单应用失败保留待重试任务。后台“订单操作”可选择“查询并核验付款”。客户状态查询只读本地状态，不会每次请求平台。

== 调度与维护 ==
回调 URL 必须公网 HTTPS 可达，不经过登录、验证码或页面缓存。允许表单 POST 并原样传递；响应 success 才表示接收完成。密钥仅保存在 WordPress 网关设置，不输出给浏览器结账脚本或公开状态接口。备份时保护 WordPress 数据库及管理权限。

配置服务器每分钟运行 WordPress 到期 cron（如 wp cron event run --due-now）；低访问站点不要仅依赖访客触发 WP-Cron。插件每批最多查询十笔，待付/确认中订单最多自动补查七天；失败五分钟后重试，正常两分钟后再查。七天后可用订单操作人工查询。停用插件停止调度但保留订单与事件数据。

修改商户账号前先处理完该账号旧订单；当前密钥用于原账号未完成订单的验签及查询。已生成订单保留原网关与通道。订单金额、币种或付款方式被修改后拒绝自动确认，须人工核对。不要在数据库中删除幂等记录来重试付款。

== 首次验收 ==
使用独立测试店铺，平台配置自己的测试商户与测试钱包。测试通道只付指定测试 USDT：检查下单、平台查询、确认中与最终通知，重发同一通知只记一次付款。平台“测试回调”仅验证连接与验签，订单备注可见，不能代替链上真实付款验收。确认回调和查询均正常后切换主网通道，并先做小额实际验收。

== Scope ==
One configured payment channel per store. No automatic refunds, subscriptions, recurring charges, RSA payload encryption or automatic exchange-rate service. Uses the existing platform MD5 signing protocol over TLS. It does not store wallet private keys or initiate blockchain transfers. Callback duplicates do not repeat payment_complete; third-party fulfilment integrations must also implement their own idempotency.

Requires 64-bit PHP, WordPress database with InnoDB and MySQL advisory-lock support, and outbound HTTPS access to the gateway. Tested on WordPress 7.1.3 / WooCommerce 11.2.1 / PHP 8.3, both legacy and HPOS storage. Earlier minimum versions are requirements, not a claim that every version was tested.

English setup: Upload ZIP, activate after WooCommerce, then Settings → Payments → VNPAYMENT. Enter merchant account/key/channel. For crypto, set store currency and quote as “1 USDT = N shop-currency units”; for ordinary payments, settlement currency must equal store currency. Use HTTPS and scheduled WordPress cron. Credentials are blank in the download. Test on a staging store first.

Online guide: https://payment.271458.xyz/doc/merchant/wp.html
