支付接口 · xxpaypro安装部署教程

# 支付接口 ## 1. 统一下单 > 接口描述业务通过统一下单接口可以发起任意三方支付渠道的支付订单。业务系统不必关心该如何调用三方支付，统一下单接口会根据业务系统选择的支付渠道ID，选择对应支付渠道的支付产品，发起下单请求，然后响应给业务系统支付请求所需参数。 > 接口链接 URL地址：{payUrl}/pay/create\_order > 请求参数字段名变量名必填类型示例值描述商户IDmchId是String(30)20001222支付中心分配的商户号应用IDappId否String(30)cbsgB1T0SL6tfflFYoBX商户应用ID支付产品IDproductId是String(24)8001商户订单号mchOrderNo是String(30)20160427210604000490商户生成的订单号支付金额amount是int100支付金额,单位分币种currency是String(3)cny三位货币代码,人民币:cny客户端IPclientIp否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测试商品描述商品描述信息支付通道子账户IDpayPassAccountId否String(256)指定通道子账号ID指定通道子账号ID附加参数extra否String(512){“openId”:”o2RvowBf7sOVJf8kJksUEMceaDqo”}特定渠道发起时额外参数扩展参数1param1否String(64)支付中心回调时会原样返回扩展参数2param2否String(64)支付中心回调时会原样返回请求时间reqTime是String(30)20190723141000请求接口时间， yyyyMMddHHmmss格式接口版本version是String(3)1.0接口版本号，固定：1.0签名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6签名值，详见签名算法> 响应结果字段名变量名必填类型示例值描述返回状态码retCode是String(16)00-处理成功，其他-处理有误，详见错误码返回信息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](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否Booleantrue如果返回true则表示商户需要主动发起订单查询当前订单状态orderStatus否String(16)2当前订单状态: -2:订单已关闭,0-订单生成,1-支付中,2-支付成功,3-业务处理完成,4-已退款（2和3都表示支付成功,3表示支付平台回调商户且返回成功后的状态）签名信息sign是String(128)CCD9083A6DAD9A2DA9F668C3D4517A84签名信息> 响应数据示例 URL方式响应数据： ``` <pre class="calibre25">``` { "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支付时响应数据： ``` <pre class="calibre25">``` { "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 > 请求参数字段名变量名必填类型示例值描述商户IDmchId是String(30)1000000010支付中心分配的商户号支付订单号payOrderId是String(30)P20160427210604000490支付中心生成的订单号，与mchOrderNo二者传一即可商户订单号mchOrderNo是String(30)20160427210604000490商户生成的订单号，与payOrderId二者传一即可是否执行回调executeNotify否Booleantrue是否执行回调，如果为true，则支付中心会再次向商户发起一次回调，如果为false则不发起请求时间reqTime是String(30)20190723141000请求接口时间， yyyyMMddHHmmss格式接口版本version是String(3)1.0接口版本号，固定：1.0签名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6签名值，详见签名算法> 响应结果字段名变量名必填类型示例值描述返回状态码retCode是String(16)00-处理成功，其他-处理有误，详见错误码返回信息retMsg否String(128)签名失败具体错误原因，例如：签名失败、参数格式校验错误##### 以下字段在retCode=0 时有返回字段名变量名必填类型示例值描述商户IDmchId是String(30)20001222支付中心分配的商户号应用IDappId否String(30)cbsgB1T0SL6tfflFYoBX商户应用ID支付产品IDproductId是String(24)8001支付订单号payOrderId是String(30)P01201907231119090520000返回支付系统订单号商户订单号mchOrderNo是String(30)20160427210604000490商户生成的订单号支付金额amount是int100支付金额,单位分币种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否Long1505049094262支付成功时间，精确到毫秒签名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6签名值，详见签名算法## 3. 支付结果通知 > 接口描述当订单支付成功时，支付中心会向商户的notifyUrl地址发起回调，通知订单状态。 > 接口链接该链接是通过统一下单接口提交的参数notifyUrl设置，如果无法访问链接，业务系统将无法接收到支付中心的通知。 > 通知参数字段名变量名必填类型示例值描述支付订单号payOrderId是String(30)P20160427210604000490支付中心生成的订单号商户IDmchId是String(30)20001222支付中心分配的商户号应用IDappId否String(30)cbsgB1T0SL6tfflFYoBX商户应用ID支付产品IDproductId是String(24)8001商户订单号mchOrderNo是String(30)20160427210604000490商户生成的订单号支付金额amount是int100支付金额,单位分入账金额income是int100入账金额,单位分状态status是int1支付状态,-2:订单已关闭,0-订单生成,1-支付中,2-支付成功,3-业务处理完成,4-已退款（2和3都表示支付成功,3表示支付平台回调商户且返回成功后的状态）渠道订单号channelOrderNo否String(64)wx2016081611532915ae15beab0167893571三方支付渠道订单号扩展参数1param1否String(64)支付中心回调时会原样返回扩展参数2param2否String(64)支付中心回调时会原样返回支付成功时间paySuccTime是long精确到毫秒通知类型backType是int1通知类型，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 > 请求参数字段名变量名必填类型示例值描述商户IDmchId是long20001222分配的商户号应用IDappId否String(32)0ae8be35ff634e2abe94f5f32f6d5c4f该商户创建的应用对应的ID支付产品IDproductId是int8000支付产品ID商户订单号mchOrderNo是String(30)20160427210604000490商户生成的订单号支付金额amount是int100支付金额,单位分支付结果前端跳转URLreturnUrl否String(128)<http://www.baidu.com/return.htm>支付结果回调URL支付结果后台回调URLnotifyUrl是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)00-处理成功，其他-处理有误，详见错误码返回信息retMsg否String(128)签名失败具体错误原因，例如：签名失败、参数格式校验错误##### 以下字段在retCode=0 时有返回字段名变量名必填类型示例值描述签名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6签名值，详见签名算法收银台URlpayUrl是String收银台地址返回的JSON格式数据如下： ``` <pre class="calibre25">``` { "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%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95&body=XXPAY%E6%94%AF%E4%BB%98%E6%B5%8B%E8%AF%95&notifyUrl=http%3A%2F%2Fwww.baidu.com&sign=9849EC1C736C72BCD59558DACA69FD6B", "retCode": "SUCCESS" } ``` ``` ## 5. 支付产品产品ID产品名称8000网银支付8001快捷支付8002微信扫码支付8003微信H5支付8004微信公众号支付8005微信小程序支付8006支付宝扫码支付8007支付宝H5支付8008支付宝服务窗支付8009QQ钱包扫码8010QQ钱包H5支付8011京东扫码支付8012京东H5支付8013百度钱包8014银联二维码8015充值卡支付8016网银B2B8017网银B2C8018支付宝PC支付8019云闪付扫码8020微信条码支付（被扫）8021支付宝条码支付（被扫）8022支付宝APP支付8023微信APP支付8024聚合码支付## 6. 错误码 RetCode描述0成功9999业务异常，具体错误详见RetMsg字段0100商户签名异常0010系统错误0011请使用post方法0012post数据为空0013签名错误0014参数错误0015商户不存在0110第三方超时0111第三方异常0112订单不存在0113订单已支付0114商品不存在0115价格不对0116物品数量不对0117过程返回2550118DB错误0119支付中心没有对应的渠道0120修改订单状态失败