xpay第三方支付平台USDT接口接入教程，实现USDT支付功能
给网站增加USDT支付功能，容易卡住的地方往往是订单状态：用户已经完成支付，网站却还显示等待付款；或者用户刚打开结果页，系统就提前发放了商品。接入xpay时，把下单、支付、回调和查单这几个环节串起来，才能让支付结果准确地回到业务系统。使用WordPress和WooCommerce搭建的网站，也可以通过适配xpay的支付插件完成配置，减少自行开发接口的工作量。
给网站增加USDT支付功能，容易卡住的地方往往是订单状态：用户已经完成支付，网站却还显示等待付款；或者用户刚打开结果页，系统就提前发放了商品。接入xpay时，把下单、支付、回调和查单这几个环节串起来，才能让支付结果准确地回到业务系统。使用WordPress和WooCommerce搭建的网站，也可以通过适配xpay的支付插件完成配置，减少自行开发接口的工作量。
1. 先确定支付场景，理清接入流程
xpay USDT支付接口接入的关键流程可以概括为：准备商户凭据 → 配置支付参数 → 生成签名 → 创建订单 → 用户完成支付 → 验证回调 → 更新订单状态。遇到通知延迟，再通过订单查询接口核实结果。
动手配置前，先确认网站需要哪一种流程。用户已经持有USDT，希望直接支付商品订单，可以选择对应的USDT支付流程；如果业务需要用户通过法币进入数字资产购买或兑换流程，则应考虑OnRamp接入。两者的订单参数和支付路径存在区别，插件也要按实际场景选择。
同时准备好商户AppID、AppSecret、接口地址，以及能够通过公网访问的HTTPS回调地址。支付网络应与账户实际开通的通道一致，不能仅凭“支持USDT”就认定任意网络都能使用。
2. 配置核心参数，先把订单信息对齐
采用API方式接入时，创建支付订单使用POST请求，接口地址为 https://xpay.plus/v1/api/open/order/submit，请求体使用JSON。主要字段可以按下面的关系理解：
| 参数 | 用途 | 配置要点 |
|---|---|---|
appId |
标识商户身份 | 填写当前账户的AppID，注意大小写 |
merchantOrderNo |
网站业务订单号 | 为每笔业务订单分配唯一编号 |
chainType |
指定支付网络 | 填写实际开通网络对应的值 |
payMoney |
订单金额 | 由服务端计算，统一金额格式 |
productName |
商品或订单名称 | 使用清楚、可识别的名称 |
notifyUrl |
接收异步支付通知 | 使用公网可访问的后端接口 |
redirectUrl |
支付后的页面跳转 | 用于展示结果，不作为成功凭据 |
signature |
请求签名 | 使用AppSecret在服务端生成 |
如果需要关联会员编号或其他业务信息，可以使用attach附加参数，但不要在其中放入密码等敏感内容。AppSecret应保存在服务器端，避免出现在网页源码、前端脚本或公开日志中。
金额也要提前约定清楚。网站商品使用其他币种标价时，需要先确定转换规则，再生成对应支付订单，不能直接把商品标价的数字当成USDT数量提交。
3. 生成签名并创建订单，拿到支付链接
签名可以按这个顺序处理：取出参与签名的参数，排除signature自身，按参数名ASCII升序排列，拼接为key=value&key2=value2，末尾追加&appsecret=你的密钥，计算MD5后将结果转为大写。
这里最容易漏掉的是字段大小写和金额格式。参与签名的数据必须与实际提交的数据保持一致，例如签名时使用10.00，请求时就不要又改成10。选填参数是否参与签名，也应与当前接口约定保持一致。
提交订单后，先检查返回的业务状态，再保存平台订单号与网站订单号的对应关系。取得payUrl后，将该链接交给前端，引导用户进入支付页面。
创建订单成功只说明支付订单已生成。 此时网站仍应保留待支付状态，不能立即发货、开通会员或发放下载权限。
4. 处理支付回调，并用查单补齐异常情况
notifyUrl和redirectUrl承担不同任务：前者接收服务器发送的支付结果，后者负责用户浏览器跳转。即使用户关闭页面，没有返回网站，后端也应能够继续处理支付通知。
接到回调后，先验证签名，再核对商户标识、业务订单号、订单金额及实付金额等信息。对于这里的USDT订单流程，status=2表示已支付或已完成；确认支付成功并且订单信息匹配后，再更新本地订单和执行后续业务。
回调可能重复到达，因此要按merchantOrderNo做幂等处理，也就是同一笔订单只执行一次发货或权益发放。首次处理成功后返回纯文本OK；已成功处理的重复通知，在完成必要校验后也应正确确认。
如果通知迟迟未到，可以通过POST请求调用https://xpay.plus/v1/api/open/order/query，提交appId、merchantOrderNo和签名查询订单。网络超时或页面未跳转，都不能直接当成支付失败，应先核实平台订单状态。
5. WordPress启用WooCommerce插件，直接填入参数
WordPress网站已经安装WooCommerce时，可以安装并启用适配xpay的WooCommerce支付插件，或者根据业务场景启用WooCommerce OnRamp插件，进入支付设置后填写参数。
WooCommerce支付插件用于接入直接支付流程，具体可用方式取决于插件版本和账户开通的通道。WooCommerce OnRamp插件用于法币OnRamp与跳转支付流程，不能仅因为名称中有支付相关描述，就把它与直接使用USDT付款视为同一种功能。
配置过程主要有四步：
- 在WordPress后台安装并启用对应插件，确认其与当前WooCommerce版本兼容。
- 进入WooCommerce支付设置，找到对应的xpay支付方式，填写商户凭据、接口地址与回调配置。
- 根据插件提供的选项设置支付方式、网络及相关参数；若插件自动生成回调地址，按该地址完成配置。
- 保存并启用支付方式，创建测试订单，检查支付页面、异步通知以及WooCommerce订单状态是否一致。
采用OnRamp流程时，还需要核对法币金额、法币币种及目标网络等配置。接口中的fiatAmount、fiatCurrency与直接支付订单的payMoney含义不同，不能机械地套用同一套参数。
插件可以简化接入操作，但保存配置后仍要完成联调。尤其要检查缓存、安全插件或访问验证是否拦截回调请求，否则可能出现支付页面正常、订单状态不更新的情况。
6. 上线前检查三个关键节点
下单是否准确。 核对商品金额、订单编号和支付网络，确认支付链接能在电脑与手机端正常打开。网络选择应展示清楚，让用户在付款前就能确认。
状态是否可靠。 测试正常支付、主动关闭页面、重复回调和通知延迟等情况。支付完成后，网站订单应正确更新；同一笔成功订单也不能重复触发业务操作。
异常是否可定位。 签名失败时，优先检查密钥、字段大小写、排序和金额格式；订单未更新时，检查回调访问日志、验签结果及查单返回值。日志保留必要的订单信息，同时隐藏密钥等敏感字段。
xpay第三方支付平台USDT接口接入完成的判断标准，是一笔订单能够从创建走到支付确认，并在网站中得到正确处理。自行开发时，把签名、回调和查单逻辑做好；使用WordPress时，选对WooCommerce支付插件或OnRamp插件，填好参数后完整走一遍订单流程。把这些节点逐一验证清楚，后续增加商品、会员服务或其他支付场景时，也更容易沿用已有配置。