开发文档

首页/开发文档

开放接口文档

收银台下单、API 下单、订单查询、退款、通知、签名和 WordPress 插件

内容与商户控制台保持同步。所有接口和签名都必须由商户服务端调用，不要在浏览器暴露商户 KEY。

notifyUrl 非必填；未配置回调时，商户必须通过查询订单接口主动确认支付结果。

当前支持：扫码支付、JSAPI 支付和支付宝 H5 支付；支付宝 H5 支付支持全部主体，暂不支持微信外浏览器 H5 支付。

主网关https://jpay.hzjianban.com

备用网关（支持 IPv6）https://api.jian-pay.com

申请退款 / 退款查询

退款接口需要先在商户控制台 API安全中开启退款权限，所有请求同样需要商户 KEY 签名。

申请退款接口POST /open/payment/refund/create

参数	类型	必填	说明
商户号 clientNo	string	是	当前订单所属商户号。
orderId	string	条件必填	简付平台订单号；orderId 和 merchantOrderNo 至少传一个。
merchantOrderNo	string	条件必填	商户支付订单号；orderId 和 merchantOrderNo 至少传一个。
refundNo	string	否	商户退款单号；不传时平台自动生成，建议商户侧传入并保证同一商户号下唯一。
refundAmount	number	是	退款金额，单位分。10 表示 0.10 元。
reason	string	否	退款原因，会记录在退款单中。
notifyUrl	string	否	本次退款结果的独立回调地址。不传则不发送退款通知，与原支付订单 notifyUrl 无关；填写后参与签名。
timestamp	string	否	请求时间戳，建议传。
sign	string	是	MD5 签名结果，小写。
sign_type	string	是	固定传 MD5。

申请退款请求示例

POST /open/payment/refund/create
Content-Type: application/json

{
  "clientNo": "JP26070612345678",
  "orderId": "PAY202607080001000001",
  "refundNo": "R202607080001",
  "refundAmount": 10,
  "reason": "用户申请退款",
  "notifyUrl": "https://example.com/refund/notify",
  "timestamp": "1783500003",
  "sign_type": "MD5",
  "sign": "md5签名"
}

退款响应字段

字段	类型	必返	说明
refundId	string	是	简付平台退款单号，后续查询退款使用。
refundNo	string	否	商户退款单号。
orderId	string	是	简付平台支付订单号。
merchantOrderNo	string	是	商户支付订单号。
clientNo	string	是	当前退款单所属商户号。
refundAmount	number	是	退款金额，单位分。
amount	number	是	退款金额，单位分，与 refundAmount 一致。
status	number	是	退款状态：0-待提交，1-处理中，2-退款成功，3-退款失败。
statusText	string	是	退款状态中文说明。
errorMessage	string	否	退款失败原因；仅退款失败或受理结果未知时返回有效内容。
createTime	string	是	退款单创建时间。
refundedAt	string	否	退款成功时间。

申请退款返回示例

{
  "code": 1000,
  "message": "success",
  "data": {
    "refundId": "RF202607081230001A2B3C4D",
    "refundNo": "R202607080001",
    "orderId": "PAY202607080001000001",
    "merchantOrderNo": "P202607080001",
    "clientNo": "JP26070612345678",
    "merchantNo": "JP26070612345678",
    "refundAmount": 10,
    "amount": 10,
    "status": 1,
    "statusText": "处理中",
    "errorMessage": "",
    "createTime": "2026-07-08 12:30:00",
    "refundedAt": null
  }
}

退款查询接口POST /open/payment/refund/query

参数	类型	必填	说明
商户号 clientNo	string	是	当前退款单所属商户号。
refundId	string	条件必填	简付平台退款单号；refundId 和 refundNo 至少传一个。
refundNo	string	条件必填	商户退款单号；refundId 和 refundNo 至少传一个。
timestamp	string	否	请求时间戳，建议传。
sign	string	是	MD5 签名结果，小写。
sign_type	string	是	固定传 MD5。

退款查询请求示例

POST /open/payment/refund/query
Content-Type: application/json

{
  "clientNo": "JP26070612345678",
  "refundId": "RF202607081230001A2B3C4D",
  "refundNo": "R202607080001",
  "timestamp": "1783500004",
  "sign_type": "MD5",
  "sign": "md5签名"
}

退款失败返回示例

{
  "code": 1000,
  "message": "success",
  "data": {
    "refundId": "RF202607081230001A2B3C4D",
    "refundNo": "R202607080001",
    "orderId": "PAY202607080001000001",
    "merchantOrderNo": "P202607080001",
    "clientNo": "JP26070612345678",
    "merchantNo": "JP26070612345678",
    "refundAmount": 10,
    "amount": 10,
    "status": 3,
    "statusText": "退款失败",
    "errorMessage": "可用余额不足",
    "createTime": "2026-07-08 12:30:00",
    "refundedAt": null
  }
}

退款状态判断

code=1000 只表示接口请求成功，不代表退款一定成功。
退款最终结果以 data.status 为准：0 待提交、1 处理中、2 退款成功、3 退款失败。
当 data.status=3 时，失败原因读取 data.errorMessage；例如余额不足、原交易不支持退款等。
当 code 不是 1000 时，表示本次接口调用失败，错误信息读取顶层 message。

退款结果回调通知

退款进入成功或失败终态后，平台会向申请退款时单独传入的 notifyUrl 发送 JSON 通知。退款回调地址与原支付订单的回调地址互不关联。

字段	说明
eventType	固定为 refund，用于区分退款通知和支付通知。
clientNo	简付商户号。
serviceProviderNo	服务商编号；通过服务商开放接口发起退款时返回。
refundId	简付平台退款单号。
refundNo	商户退款单号。
orderId	原支付订单的简付平台订单号。
merchantOrderNo	原支付订单的商户订单号。
refundAmount	退款金额，单位分。
status	退款状态：2-退款成功，3-退款失败。
statusText	退款状态中文说明。
errorMessage	退款失败原因；成功时为空字符串。
refundedAt	退款成功时间，格式 YYYY-MM-DD HH:mm:ss；失败时为空字符串。
sign	通知签名，商户必须使用商户 KEY 验签。
sign_type	固定为 MD5。

退款成功通知示例

{
  "eventType": "refund",
  "clientNo": "JP26070612345678",
  "refundId": "RF202607081230001A2B3C4D",
  "refundNo": "R202607080001",
  "orderId": "PAY202607080001000001",
  "merchantOrderNo": "P202607080001",
  "refundAmount": 10,
  "status": 2,
  "statusText": "退款成功",
  "errorMessage": "",
  "refundedAt": "2026-07-08 12:40:00",
  "sign_type": "MD5",
  "sign": "md5签名"
}

通知处理要求

通过 eventType=refund 区分退款通知和支付通知。
收到通知后先验签，并按 refundId 或 refundNo 做幂等处理。
处理成功后返回纯字符串 success；未返回时平台会重试通知。
申请退款时未传 notifyUrl，平台不会发送退款通知，请主动调用退款查询接口确认最终结果。