大约 16 分钟
统一下单
接口描述
业务通过统一下单接口可以发起任意三方支付渠道的支付订单。业务系统不必关心该如何调用三方支付，统一下单接口会根据业务系统选择的支付渠道ID，选择对应支付渠道的支付产品，发起下单请求，然后响应给业务系统支付请求所需参数。
接口链接
URL地址：{payUrl}/pay/create_order
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
| 应用ID | appId | 否 | String(30) | cbsgB1T0SL6tfflFYoBX | 商户应用ID |
| 支付产品ID | productId | 是 | String(24) | 8001 | |
| 商户订单号 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商户生成的订单号 |
| 支付金额 | amount | 是 | int | 100 | 支付金额,单位分 |
| 币种 | currency | 是 | String(3) | cny | 三位货币代码,人民币:cny |
| 客户端IP | clientIp | 否 | String(32) | 210.73.10.148 | 客户端IP地址 |
| 设备 | device | 否 | String(64) | ios10.3.1 | 客户端设备 |
| 异步回调地址 | notifyUrl | 是 | String(128) | http://shop.xx.com/notify.htm | 支付结果异步回调URL |
| 同步请求地址 | returnUrl | 否 | String(128) | http://shop.xx.com/return.htm | 支付结果同步请求URL |
| 商品主题 | subject | 是 | String(64) | xxpay测试商品1 | 商品主题 |
| 商品描述信息 | body | 是 | String(256) | xxpay测试商品描述 | 商品描述信息 |
| 支付通道子账户ID | payPassAccountId | 否 | String(256) | 指定通道子账号ID | 指定通道子账号ID |
| 附加参数 | extra | 否 | String(512) | {“openId”:”o2RvowBf7sOVJf8kJksUEMceaDqo”} | 特定渠道发起时额外参数 |
| 扩展参数1 | param1 | 否 | String(64) | 支付中心回调时会原样返回 | |
| 扩展参数2 | param2 | 否 | String(64) | 支付中心回调时会原样返回 | |
| 请求时间 | reqTime | 是 | String(30) | 20190723141000 | 请求接口时间， yyyyMMddHHmmss格式 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本号，固定：1.0 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
响应结果
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因，例如：签名失败、参数格式校验错误 |
以下字段在retCode=0 时有返回
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 支付订单号 | payOrderId | 是 | String(30) | P01201907231119090520000 | 返回支付系统订单号 |
| 支付方式 | payMethod | 是 | String(16) | formJump | 支付方式，目前包含两种： formJump-表单跳转，codeImg-二维码图片，wxApp-微信app支付，alipayApp-支付宝app支付，wxJSApi-微信公众号支付 |
| 支付表单地址 | payUrl | 否 | text | | payMethod=formJump时存在该参数； 一般为支付表单内容 |
| 支付跳转地址 | payJumpUrl | 否 | text | 支付跳转地址，可直接重定向的URL | |
| 表单提交方式 | payAction | 否 | String(16) | GET | 指定表单提交方式: POST/GET |
| 二维码地址 | codeUrl | 否 | String(16) | https://qr.alipay.com/bax08687odiyi06c | payMethod=codeImg时存在该参数； 二维码内容地址 |
| 二维码图片地址 | codeImgUrl | 否 | String(16) | http://pay.xxpay.org/api/qrcode_img_get?url=https://qr.alipay.com/bax08687z006c&width=200&height=200 | payMethod=codeImg时存在该参数； 二维码图片地址 |
| 支付自定义参数 | payParams | 否 | String(16) | 支付自定义参数，当payMethod为支付宝app、微信app或微信公众号支付时，该参数有值，取appStr字段 | |
| 是否需要查单 | needQuery | 否 | Boolean | true | 如果返回true则表示商户需要主动发起订单查询 |
| 当前订单状态 | orderStatus | 否 | String(16) | 2 | 当前订单状态: -2:订单已关闭,0-订单生成,1-支付中,2-支付成功,3-业务处理完成,4-已退款（2和3都表示支付成功,3表示支付平台回调商户且返回成功后的状态） |
| 签名信息 | sign | 是 | String(128) | CCD9083A6DAD9A2DA9F668C3D4517A84 | 签名信息 |
响应数据示例
URL方式响应数据：
{
"payJumpUrl": "http://170.33.8.116:8182/payurl?mchOrderId=Pnull202011171714049724732&amount=686.00",
"payMethod": "formJump",
"payUrl": "<script>window.location.href = http://170.33.8.116:8182/payurl?mchOrderId=Pnull202011171714049724732&amount=686.00</script>",
"retCode": "0",
"sign": "3251661E4B84AAB6BAA1A6A025F40036"
}APP支付时响应数据：
{
"payMethod": "alipayApp",
"payParams": {
"appStr": "trade_no=2020111704200341411064884895&biz_sub_type=peerpay_trade&presessionid=&app=tb&channel=&type2=gulupay&bizcontext={\"biz_type\":\"share_pp_pay\",\"type\":\"qogirpay\"}"
},
"retCode": "0",
"sign": "6734227C78A110D7F9BF94BB9A217D3E"
}2. 查询支付订单
接口描述
业务系统通过查询支付订单接口获取最新的支付订单状态，并根据状态结果进一步处理业务逻辑。
接口链接
URL地址：{payUrl}/pay/query_order
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 1000000010 | 支付中心分配的商户号 |
| 支付订单号 | payOrderId | 是 | String(30) | P20160427210604000490 | 支付中心生成的订单号，与mchOrderNo二者传一即可 |
| 商户订单号 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商户生成的订单号，与payOrderId二者传一即可 |
| 是否执行回调 | executeNotify | 否 | Boolean | true | 是否执行回调，如果为true，则支付中心会再次向商户发起一次回调，如果为false则不发起 |
| 请求时间 | reqTime | 是 | String(30) | 20190723141000 | 请求接口时间， yyyyMMddHHmmss格式 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本号，固定：1.0 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
响应结果
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因，例如：签名失败、参数格式校验错误 |
响应结果
以下字段在retCode=0 时有返回
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
| 应用ID | appId | 否 | String(30) | cbsgB1T0SL6tfflFYoBX | 商户应用ID |
| 支付产品ID | productId | 是 | String(24) | 8001 | |
| 支付订单号 | payOrderId | 是 | String(30) | P01201907231119090520000 | 返回支付系统订单号 |
| 商户订单号 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商户生成的订单号 |
| 支付金额 | amount | 是 | int | 100 | 支付金额,单位分 |
| 币种 | currency | 是 | String(3) | cny | 三位货币代码,人民币:cny |
| 订单状态 | status | 是 | String(3) | 2 | 当前订单状态: -2:订单已关闭,0-订单生成,1-支付中,2-支付成功,3-业务处理完成,4-已退款（2和3都表示支付成功,3表示支付平台回调商户且返回成功后的状态） |
| 渠道用户 | channelUser | 否 | String | 渠道用户 | |
| 渠道订单号 | channelOrderNo | 否 | String wx20170910211043fb206e92260071822007 | 对应的第三方支付订单号 | |
| 渠道数据包 | channelAttach | 否 | String | 渠道数据包 | |
| 支付成功时间 | paySuccTime | 否 | Long | 1505049094262 | 支付成功时间，精确到毫秒 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
3. 支付结果通知
接口描述
当订单支付成功时，支付中心会向商户的notifyUrl地址发起回调，通知订单状态。
接口链接
该链接是通过统一下单接口提交的参数notifyUrl设置，如果无法访问链接，业务系统将无法接收到支付中心的通知。
通知参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 支付订单号 | payOrderId | 是 | String(30) | P20160427210604000490 | 支付中心生成的订单号 |
| 商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
| 应用ID | appId | 否 | String(30) | cbsgB1T0SL6tfflFYoBX | 商户应用ID |
| 支付产品ID | productId | 是 | String(24) | 8001 | |
| 商户订单号 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商户生成的订单号 |
| 支付金额 | amount | 是 | int | 100 | 支付金额,单位分 |
| 入账金额 | income | 是 | int | 100 | 入账金额,单位分 |
| 状态 | status | 是 | int | 1 | 支付状态,-2:订单已关闭,0-订单生成,1-支付中,2-支付成功,3-业务处理完成,4-已退款（2和3都表示支付成功,3表示支付平台回调商户且返回成功后的状态） |
| 渠道订单号 | channelOrderNo | 否 | String(64) | wx2016081611532915ae15beab0167893571 | 三方支付渠道订单号 |
| 扩展参数1 | param1 | 否 | String(64) | 支付中心回调时会原样返回 | |
| 扩展参数2 | param2 | 否 | String(64) | 支付中心回调时会原样返回 | |
| 支付成功时间 | paySuccTime | 是 | long | 精确到毫秒 | |
| 通知类型 | backType | 是 | int | 1 | 通知类型，1-前台通知，2-后台通知 |
| 通知请求时间 | reqTime | 是 | String(30) | 20190723141000 | 通知请求时间，yyyyMMddHHmmss格式 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
返回结果
业务系统处理后同步返回给支付中心，返回字符串 success 则表示成功，返回非success则表示处理失败，支付中心会再次通知业务系统。（通知频率为60/120/180/240/300,单位：秒）
注意：返回的字符串必须是小写，且前后不能有空格。
4. 创建收银台(废弃)
接口描述
业务通过创建收银台接口得到收银台地址URl，用户打开收银台URL进入支付流程。
接口链接
创建PC收银台接口地址：{payUrl}/cashier/pc_build
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | long | 20001222 | 分配的商户号 |
| 应用ID | appId | 否 | String(32) | 0ae8be35ff634e2abe94f5f32f6d5c4f | 该商户创建的应用对应的ID |
| 支付产品ID | productId | 是 | int | 8000 | 支付产品ID |
| 商户订单号 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商户生成的订单号 |
| 支付金额 | amount | 是 | int | 100 | 支付金额,单位分 |
| 支付结果前端跳转URL | returnUrl | 否 | String(128) | http://www.baidu.com/return.htm | 支付结果回调URL |
| 支付结果后台回调URL | notifyUrl | 是 | String(128) | http://www.baidu.com/notify.htm | 支付结果回调URL |
| 商品主题 | subject | 是 | String(64) | xxpay测试商品1 | 商品主题 |
| 商品描述信息 | body | 是 | String(256) | xxpay测试商品描述 | 商品描述信息 |
| 请求时间 | reqTime | 是 | String(30) | 20190723141000 | 请求接口时间， yyyyMMddHHmmss格式 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本号，固定：1.0 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
响应结果
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因，例如：签名失败、参数格式校验错误 |
以下字段在retCode=0 时有返回
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
| 收银台URl | payUrl | 是 | String | 收银台地址 |
收银台地址
返回的JSON格式数据如下：
{
"sign": "5AAD2B9513ADE7E0C76A4BC99E1A92F0",
"payUrl": "http://127.0.0.1:3020/api/cashier/pc?mchId=20000000&appId=710ddfebd2154434a8cfee1807b27eea&productId=8000,8001&amount=1&mchOrderNo=1528684776204&subject=XXPAY支付测试&body=XXPAY支付测试¬ifyUrl=http://www.baidu.com&sign=9849EC1C736C72BCD59558DACA69FD6B",
"retCode": "SUCCESS"
}5. 支付产品
| 产品ID | 产品名称 |
|---|---|
| 8000 | 网银支付 |
| 8001 | 快捷支付 |
| 8002 | 微信扫码支付 |
| 8003 | 微信H5支付 |
| 8004 | 微信公众号支付 |
| 8005 | 微信小程序支付 |
| 8006 | 支付宝扫码支付 |
| 8007 | 支付宝H5支付 |
| 8008 | 支付宝服务窗支付 |
| 8009 | QQ钱包扫码 |
| 8010 | QQ钱包H5支付 |
| 8011 | 京东扫码支付 |
| 8012 | 京东H5支付 |
| 8013 | 百度钱包 |
| 8014 | 银联二维码 |
| 8015 | 充值卡支付 |
| 8016 | 网银B2B |
| 8017 | 网银B2C |
| 8018 | 支付宝PC支付 |
| 8019 | 云闪付扫码 |
| 8020 | 微信条码支付（被扫） |
| 8021 | 支付宝条码支付（被扫） |
| 8022 | 支付宝APP支付 |
| 8023 | 微信APP支付 |
| 8024 | 聚合码支付 |
6. 错误码
| RetCode | 描述 |
|---|---|
| 0 | 成功 |
| 9999 | 业务异常，具体错误详见RetMsg字段 |
| 0100 | 商户签名异常 |
| 0010 | 系统错误 |
| 0011 | 请使用post方法 |
| 0012 | post数据为空 |
| 0013 | 签名错误 |
| 0014 | 参数错误 |
| 0015 | 商户不存在 |
| 0110 | 第三方超时 |
| 0111 | 第三方异常 |
| 0112 | 订单不存在 |
| 0113 | 订单已支付 |
| 0114 | 商品不存在 |
| 0115 | 价格不对 |
| 0116 | 物品数量不对 |
| 0117 | 过程返回255 |
| 0118 | DB错误 |
| 0119 | 支付中心没有对应的渠道 |
| 0120 | 修改订单状态失败 |