XPay 商户对接文档

概述与基础约定

本文档面向接入 XPay 的下游商户，描述代收（收款）、代付（出款）及各类查询接口的调用方式。请先通读本节的基础约定。

项目	说明
网关地址	https://api.xpay24.net
商户号 / 密钥	由 XPay 开户时提供。`merchantId`（数字商户号）+ `secretKey`（签名密钥）。
请求方式	全部为 POST，`Content-Type: application/json;charset=UTF-8`
金额单位	派萨 / 分（paise），整数。例：100.00 卢比 → 传 `10000`。
timestamp	毫秒级时间戳（long）。服务器校验有效期为 ±5 分钟，过期拒绝。
字符编码	UTF-8

请求成功（code=200）≠ 付款成功。 下单接口返回 200 仅表示受理成功，最终支付/出款结果以异步回调或查询接口为准。

签名规则

所有接口都需要签名字段 sign（MD5，32 位小写十六进制）。根据接口是否携带订单号，签名公式分两种：

① 带订单号的接口（下单、补单、订单查询）

SIGN sign = md5( orderId + timestamp + secretKey )

② 不带订单号的接口（UPI 查询 / UTR 查询 / 余额查询）

SIGN sign = md5( merchantId + timestamp + secretKey )

拼接时直接把值按顺序连成一个字符串再做 MD5，中间无任何分隔符。用于签名的 timestamp 必须与请求体里的完全一致。

签名示例

设 orderId=ORDER20260720001、timestamp=1785000000000、secretKey=your_secret_key：

待签字符串 = "ORDER202607200011785000000000your_secret_key"
sign = md5(上面字符串) = 32位小写

验证回调签名时：sign 字段本身不参与运算，用其余参数按同样公式算出签名再与 sign 比对。

代收下单

创建一笔代收（收款）订单，成功后返回支付链接 paymentUrl，引导用户完成支付。

POST /v1/orders/create

请求参数

字段	类型	必填	说明
merchantId	long	是	商户号
amount	long	是	金额（派萨/分），整数
currency	string	否	币种，默认 `INR`
orderId	string	是	商户订单号（≤50，商户侧唯一）
notifyUrl	string	是	接收本笔订单异步回调的地址（≤255）
idempotencyKey	string	否	幂等键；相同键重复提交返回同一订单
timestamp	long	是	毫秒时间戳
sign	string	是	md5(orderId + timestamp + secretKey)

请求示例

POST /v1/orders/create
{
  "merchantId": 101,
  "amount": 10000,
  "currency": "INR",
  "orderId": "ORDER20260720001",
  "notifyUrl": "https://your-site.com/xpay/collect/notify",
  "timestamp": 1785000000000,
  "sign": "e10adc3949ba59abbe56e057f20f883e"
}

响应参数

字段	类型	说明
code	int	200 = 受理成功
msg	string	提示信息 / 错误码
payOrderId	string	XPay 平台订单号
orderNo	string	平台订单号（同 payOrderId）
orderId	string	商户订单号（原样返回）
amount	long	金额（分）
currency	string	币种
status	string	订单状态，下单成功为 `INITIATED`（待支付）
paymentUrl	string	支付链接（透传）：由上游返回、XPay 原样透传给商户，商户直接用它拉起收银台供用户支付。仅成功时返回。

响应示例

{
  "code": 200,
  "msg": "Success",
  "payOrderId": "X_PAYIN2607201230482KQ",
  "orderNo": "X_PAYIN2607201230482KQ",
  "orderId": "ORDER20260720001",
  "amount": 10000,
  "currency": "INR",
  "status": "INITIATED",
  "paymentUrl": "https://<上游收银台链接，原样透传>"
}

代收补单（UTR）

当用户已完成付款但订单仍未自动置为成功时，商户可提交银行流水号 UTR 进行人工补单。系统会向上游核验该 UTR，核验通过即置为成功。

POST /v1/orders/complete-with-utr

请求参数

字段	类型	必填	说明
merchantId	long	是	商户号
orderId	string	是	商户订单号
utr	string	是	银行流水号 UTR（≤50）
remark	string	否	备注
timestamp	long	是	毫秒时间戳
sign	string	是	md5(orderId + timestamp + secretKey)

响应示例

{
  "code": 200,
  "msg": "Success",
  "orderNo": "X_PAYIN2607201230482KQ",
  "orderId": "ORDER20260720001",
  "amount": 10000,
  "currency": "INR",
  "status": "SUCCESS"
}

若该 UTR 已被其它订单占用，或上游核验未通过，接口返回相应错误码（code≠200），订单状态不变。

代收订单查询

按商户订单号查询代收订单当前状态。

POST /v1/query/collect/status

请求参数

字段	类型	必填	说明
merchantId	long	是	商户号
orderId	string	是	商户订单号
timestamp	long	是	毫秒时间戳
sign	string	是	md5(orderId + timestamp + secretKey)

响应参数

字段	类型	说明
code	int	200 = 成功，404 = 订单不存在
msg	string	提示信息
status	string	INITIATED 待支付SUCCESS 成功REFUNDED 已退款
amount	long	金额（分）
orderNo	string	平台订单号
utr	string	银行流水号（成功且已回填时返回）

响应示例

{
  "code": 200,
  "msg": "Success",
  "status": "SUCCESS",
  "amount": 10000,
  "orderNo": "X_PAYIN2607201230482KQ",
  "utr": "123456789012"
}

代收异步回调

当代收订单支付成功或失败时，XPay 会主动 POST（JSON）到你下单时传入的 notifyUrl。仅在成功/失败时推送。

通知参数

字段	类型	说明
amount	long	金额（分）
merchantId	long	商户号
orderId	string	商户订单号
payOrderId	string	平台订单号
status	int	1 = 支付成功2 = 支付失败
utr	string	银行流水号（成功时可能返回，否则为 `null`）
timestamp	long	毫秒时间戳
sign	string	md5(orderId + timestamp + secretKey)，用于验签

通知示例

POST https://your-site.com/xpay/collect/notify
Content-Type: application/json
X-Signature: <HmacSHA256(body, secretKey) 十六进制，附加校验头>

{
  "amount": 10000,
  "merchantId": 101,
  "orderId": "ORDER20260720001",
  "payOrderId": "X_PAYIN2607201230482KQ",
  "status": 1,
  "utr": "123456789012",
  "timestamp": 1785000000000,
  "sign": "a1b2c3d4e5f6..."
}

验签：用请求体里除 sign 外的参数，按 md5(orderId + timestamp + secretKey) 算出后与 sign 比对。请求头 X-Signature 是对整个 body 的 HmacSHA256（十六进制）附加校验，可选用于额外完整性校验。

商户必须在 5 秒内返回字符串 SUCCESS 或 OK（HTTP 2xx）。否则视为接收失败，XPay 约每 5 分钟重推一次、最多 5 次。请先验签再处理业务，并做好幂等（同一订单可能被推送多次）。

代付下单

发起一笔代付（出款）订单。受理成功后进入处理中，最终结果以异步回调或查询为准。

POST /v1/payouts/create

IP 白名单：代付接口要求来源 IP 在商户白名单内，否则返回 IP error。请提前把出款服务器 IP 提供给 XPay 加入白名单。

请求参数

字段	类型	必填	说明
merchantId	long	是	商户号
amount	long	是	金额（分）
currency	string	否	默认 INR
orderId	string	是	商户订单号（≤50）
notifyUrl	string	是	代付结果回调地址（≤255）
payoutType	string	是	出款类型：`IMPS` 或 `UPI`
accountHolder	string	是	收款人姓名（仅英文字母或空格，3–50）
accountNumber	string	是	收款账号（5–35）；UPI 出款时填收款 UPI 地址
ifsc	string	条件	IMPS 出款必填；UPI 出款可不填
idempotencyKey	string	否	幂等键
timestamp	long	是	毫秒时间戳
sign	string	是	md5(orderId + timestamp + secretKey)

请求示例

POST /v1/payouts/create
{
  "merchantId": 101,
  "amount": 50000,
  "currency": "INR",
  "orderId": "PAYOUT20260720001",
  "notifyUrl": "https://your-site.com/xpay/payout/notify",
  "payoutType": "IMPS",
  "accountHolder": "RAHUL KUMAR",
  "accountNumber": "1234567890",
  "ifsc": "SBIN0001234",
  "timestamp": 1785000000000,
  "sign": "5f4dcc3b5aa765d61d8327deb882cf99"
}

响应示例

{
  "code": 200,
  "msg": "Success",
  "payoutNo": "X_PAYOUT2607201230477QN",
  "orderId": "PAYOUT20260720001",
  "amount": 50000,
  "currency": "INR",
  "status": "PROCESSING"
}

受理成功后订单进入 PROCESSING（处理中）；若被上游同步拒绝，进入人工处理并携带拒绝原因。最终以异步回调为准。

代付订单查询

POST /v1/query/payout/status

请求参数

字段	类型	必填	说明
merchantId	long	是	商户号
orderId	string	是	商户订单号
timestamp	long	是	毫秒时间戳
sign	string	是	md5(orderId + timestamp + secretKey)

响应参数

字段	类型	说明
code	int	200 = 成功，404 = 不存在
msg	string	提示信息
status	string	INITIATED 待处理PROCESSING 处理中SUCCESS 成功FAILED 失败
amount	long	金额（分）
orderNo	string	平台代付单号
utr	string	银行流水号（成功时返回）

代付异步回调

代付成功或失败时，XPay 主动 POST（JSON）到 notifyUrl。

通知参数

字段	类型	说明
amount	long	金额（分）
merchantId	long	商户号
orderId	string	商户订单号
payOrderId	string	平台代付单号
status	int	1 = 代付成功2 = 代付失败
statusDesc	string	状态描述：`success` / `failed`
utr	string	银行流水号（成功时返回，否则 `null`）
timestamp	long	毫秒时间戳
sign	string	md5(orderId + timestamp + secretKey)

通知示例

{
  "amount": 50000,
  "merchantId": 101,
  "orderId": "PAYOUT20260720001",
  "payOrderId": "X_PAYOUT2607201230477QN",
  "status": 1,
  "statusDesc": "success",
  "utr": "998877665544",
  "timestamp": 1785000000000,
  "sign": "a1b2c3d4e5f6..."
}

同代收回调：5 秒内返回 SUCCESS 或 OK，否则约每 5 分钟重推、最多 5 次。请先验签再处理、并做幂等。代付失败时款项退回商户余额。

UPI 归属查询

查询某个 UPI 地址是否属于本平台通道。

POST /v1/query/upi/query

请求参数

字段	类型	必填	说明
merchantId	long	是	商户号
upi	string	是	待查询的 UPI 地址
timestamp	long	是	毫秒时间戳
sign	string	是	md5(merchantId + timestamp + secretKey)

响应参数

字段	类型	说明
belongsToUs	bool	true = 属于本平台，false = 不属于
message	string	说明

响应示例

{
  "belongsToUs": true,
  "message": "UPI belongs to current platform"
}

UTR 到账查询

按银行流水号 UTR 查询是否到账、是否已被订单匹配。

POST /v1/query/utr

请求参数

字段	类型	必填	说明
merchantId	long	是	商户号
utr	string	是	银行流水号 UTR
timestamp	long	是	毫秒时间戳
sign	string	是	md5(merchantId + timestamp + secretKey)

响应参数

字段	类型	说明
received	bool	是否已到账
matched	bool	是否已被订单匹配
matchedOrderId	string	匹配到的商户订单号（matched=true 时）
amount	long	金额（分，若有）
message	string	说明。未到账时系统自动挂入排查轮询

余额查询

POST /v1/query/balance

等价接口：POST /v1/balance/query

请求参数

字段	类型	必填	说明
merchantId	long	是	商户号
timestamp	long	是	毫秒时间戳
sign	string	是	md5(merchantId + timestamp + secretKey)

响应示例

{
  "balance": 1234500
}

字段	类型	说明
balance	long	可用余额（分）

错误码

接口失败时通过 code / msg 返回。常见错误：

msg	含义
Signature verification failed	签名错误
Timestamp expired	时间戳超出 ±5 分钟
Invalid merchantId	商户号不存在
Merchant is currently disabled	商户已被禁用
IP not whitelisted	代付来源 IP 不在白名单
Amount out of range	金额超出限额
Duplicate orderId	订单号重复
Insufficient balance	商户余额不足（代付）
Order not found	订单不存在

集成步骤

代收

1. 调 /v1/orders/create 下单；
2. 用返回的 paymentUrl（上游透传）打开收银台供用户支付；
3. 接收异步回调（notifyUrl），验签后按 status 处理订单，返回 SUCCESS；
4. 需要时用 /v1/query/collect/status 主动查询兜底。

代付

1. 把出款服务器 IP 提供给 XPay 加白名单；
2. 调 /v1/payouts/create 发起出款；
3. 接收异步回调，验签后处理结果；
4. 需要时用 /v1/query/payout/status 查询。

务必：金额用分为单位；每次请求 timestamp 用当前毫秒时间；回调一律先验签再处理并做幂等；一切支付结果以异步回调 / 查询接口为准。

XPay 商户对接文档 · v1 · 如有疑问请联系对接技术支持