API 总览

XArrPay 商户版对外提供一套 HTTP 支付接口，供你的业务系统（下游）发起下单、查单、关单，并接收支付结果回调。所有对外接口均挂载在 /xpay/ 网关下。

网关地址

https://你的部署域名/xpay/

例如下单接口完整地址为 https://pay.example.com/xpay/order/create。

支持的协议

XArrPay 同时兼容多套下单协议，你可以按下游系统已有的对接习惯任选其一：

协议	说明	文档
XArrPay 原生协议	平台自带协议，MD5 签名，字段清晰，推荐新接入使用	XArrPay 原生协议
易支付 V1	兼容彩虹易支付 submit.php / mapi.php / api.php，MD5 签名	易支付协议 V1
易支付 V2（epayn）	彩虹易支付新版协议，RSA-SHA256 双向签名	易支付 V2 协议
虎皮椒	兼容虎皮椒下单协议，hash 字段 MD5 签名	虎皮椒协议
V免签	兼容 V免签 createOrder / getOrder / checkOrder	通道 · V免签

通用约定

请求方式

• 除特别说明外，接口均为 POST，请求体支持 application/x-www-form-urlencoded 或 application/json。
• 每个请求都必须携带商户 pid 与 sign 签名。

统一响应结构

除页面型接口（如 create-page 直接 302 跳转、create 结果页）外，接口返回统一 JSON 结构：

{
  "code": 200,
  "msg": "success",
  "data": { }
}

字段	类型	说明
code	int	状态码，200 表示成功，其余为失败
msg	string	提示信息
data	object	业务数据，具体结构见各接口

常见错误码：

code	含义
200	成功
403	签名校验失败
404	商户不存在 / 订单未找到
502	下单失败（渠道异常等）

商户凭证

对接所需的 商户 ID（pid） 与 商户密钥（AppSecret） 在用户中心获取，密钥用于请求签名与回调验签，请妥善保管、切勿泄露。

金额单位

注意金额单位差异

• 下单请求（money）与下单响应（amount / trade_amount）单位为 元（字符串，如 "0.01"）。
• 异步/同步回调中的 amount / trade_amount 单位为 分（整数，如 1）。

对接时请务必按接口分别处理，避免金额错位。

订单状态

状态值	含义
1	待支付
2	已支付
3	已关闭
4	已超时
5	创建失败

签名算法

XArrPay 原生协议、易支付 V1、V免签均采用 MD5 签名，规则一致：

1. 取所有参与签名的参数（排除 sign、sign_type 以及值为空的字段）。
2. 按参数名 ASCII 升序 排序。
3. 以 key1=value1&key2=value2&...&keyN=valueN 拼接（末尾无 &）。
4. 在拼接串末尾直接追加商户密钥 AppSecret（无分隔符）。
5. 对最终字符串计算 MD5，取 32 位小写十六进制，即为 sign。

易支付 V2（epayn）使用 RSA-SHA256 双向签名，规则不同，见对应协议说明。

详见 XArrPay 原生协议 · 签名算法。