xpay第三方支付平台支付宝接口接入教程，实现支付宝支付功能

给网站加上支付宝支付，真正需要打通的是从提交订单到更新订单状态的完整流程。接入xpay第三方支付平台时，可以按“准备凭据、配置接口、创建订单、打开支付页面、验证支付结果”的顺序推进。WordPress网站可以通过适配的WooCommerce插件完成配置，自建网站则由后端调用接口。两种方式都要检查支付完成后的订单状态，不能只看页面是否成功跳转。

1. 接入前准备：分清两套应用凭据

配置xpay支付宝直连支付，需要准备两套用途不同的凭据。第一套是xpay的AppID和AppSecret，用于识别商户身份、生成请求签名以及验证支付通知；第二套是支付宝应用AppID、应用私钥和支付宝公钥，需要在xpay后台的应用凭据中配置，并完成审核和启用。

这里最容易填错的是AppID。调用xpay接口时，appId填写xpay的AppID，签名使用xpay的AppSecret。支付宝应用信息有单独的配置位置，不能把两套参数混在一起。开始测试前，还要确认下单权限已开启，网站HTTPS访问正常，后端通知地址能够从公网访问。

 

2. WordPress接入：启用WooCommerce插件并填写参数

已经安装WooCommerce的WordPress网站，可以启用适配xpay的WooCommerce支付插件，或根据业务需要选择WooCommerce OnRamp插件，在设置页面直接填入参数。基础配置可以按下面的顺序完成：

1. 在WordPress后台安装并启用对应插件，确认当前WordPress、WooCommerce与插件版本兼容。
2. 进入WooCommerce的支付设置，找到对应支付方式，打开配置页面。
3. 按字段要求填写商户凭据、接口地址和回调地址；涉及密钥的项目，核对是否要求填写xpay AppSecret。
4. 如果当前插件与已开通通道支持支付宝，启用相应选项，保存后到结算页面检查展示情况。

普通商品订单可以优先考虑WooCommerce支付插件；WooCommerce OnRamp插件面向法币OnRamp与跳转支付流程，选择时要确认与业务匹配。两款插件的用途并不完全相同，不能默认所有版本都具有相同的支付宝选项。插件已生成回调地址时，应使用该地址；接口地址字段要求填写基础地址还是完整路径，也要按当前配置项区分。

 

3. 自建网站接入：整理支付宝下单参数

自建网站可以由后端通过POST请求调用https://xpay.plus/v1/api/open/order/submit，请求体使用JSON。采用支付宝直连方式时，核心参数如下：

参数	填写要求
appId	必填，填写xpay AppID
merchantOrderNo	必填，网站生成的商户订单号
payType	必填，固定填写ALIPAY
payMethod	必填，电脑网站填写web，手机网站填写wap
amount	必填，人民币金额，大于0且最多两位小数
notifyUrl	必填，用于接收支付结果的后端通知地址
signature	必填，由后端使用xpay AppSecret生成
redirectUrl	选填，支付完成后返回的网站页面
productName	选填，建议填写清楚的商品名称
credentialId	选填，指定当前商户已审核并启用的支付宝凭据记录

网站应先保存本地订单，再发起支付请求。订单金额由后端根据商品、优惠和运费计算，不能直接信任浏览器传来的金额。同一订单号重试时，金额和支付方式必须与首次请求一致；首次指定了credentialId，重试也要保持相同值。

 

4. 生成签名：提交订单并打开支付页面

xpay支付宝接口签名的基本顺序是：去除signature和空值字段，将其余字段按字段名ASCII升序排列，拼接成查询字符串，再在末尾追加&appsecret=实际的xpay商户密钥，计算MD5并转换为大写。实际提交的非空字段都要参与签名，字段名称区分大小写，签名后也不要再修改金额或其他参数。

订单创建成功后，后端读取返回数据中的payUrl，交给用户浏览器打开支付页面。电脑端使用web，手机浏览器使用wap。这一步只表示支付订单已经创建，网站仍应保持待支付状态。AppSecret和签名计算过程应留在服务端，避免把密钥放进网页源码。

 

5. 处理支付回调：确认结果后再更新订单

notifyUrl和redirectUrl承担不同任务：前者接收服务器发送的支付通知，后者负责用户浏览器跳转。用户可能支付后直接关闭页面，也可能反复刷新结果页，因此订单是否支付成功，应通过经过验证的异步通知或查单结果确认。

支付宝直连通知以表单格式POST到notifyUrl。网站需要使用xpay AppSecret重新计算签名，核对商户身份、订单号、金额及支付状态，再更新本地订单。该通知中的成功状态为PAID；支付宝直连查单结果中的status=2表示已支付，两者不要混用。

回调处理还要防止重复执行：同一笔订单收到多次有效通知，只能触发一次发货、库存扣减或权益开通。成功处理后，可以返回HTTP 200和纯文本success确认接收。暂时没有收到通知时，可调用/v1/api/open/order/query查询，并携带payType=ALIPAY等必要参数完成核实。

6. 上线测试：检查支付与订单是否一致

完成xpay支付宝支付接口配置后，建议使用允许范围内的小额订单验证以下节点：

1. 结算展示： 商品金额、优惠、运费和最终支付金额一致，支付宝选项能够正常选择。
2. 终端跳转： 分别在电脑和手机浏览器测试，确认支付页面能够打开，返回页面没有异常。
3. 状态更新： 支付完成后检查WooCommerce或自建系统的订单记录，确认相关订单操作正常触发。
4. 异常处理： 检查取消支付、关闭页面、重复通知等情况，避免未支付订单被标记成功，或已支付订单被重复处理。

 

7. 常见问题：按报错定位配置位置

提示签名错误怎么办？ 先检查xpay AppSecret是否填写正确，再检查字段排序、大小写和空值过滤。金额字符串也要保持一致，例如签名时使用20.00，提交时就不要改成20。

提示支付宝凭据不可用怎么办？ 检查应用凭据是否属于当前商户，是否已审核、已启用，以及指定的credentialId是否正确。只填好接口密钥，并不代表支付宝应用凭据已经配置完成。

支付完成后订单仍然待支付怎么办？ 优先检查通知地址能否访问、服务器是否收到请求、回调验签是否通过，以及订单更新是否报错。WordPress网站还应查看插件日志，确认缓存或安全插件没有拦截通知请求，并通过查单核实实际支付结果。

xpay第三方支付平台支付宝接口接入的关键，在于让网站订单、支付请求和最终结果对应起来。WordPress网站使用适配的WooCommerce支付插件或OnRamp插件，可以减少手动开发工作；自建系统则需要把签名、通知验证和订单查询接好。等电脑端、手机端以及异常场景都验证通过，再开放给用户使用，后续维护也会更省心。