下单接口
正式地址: https://pay.xx.com/pub/order/pay
测试地址: https://pay.xx.com/test/order/pay
请求方式: POST
请求参数
参数 | 类型 | 是否必填 | 最大长度 | 描述 | 实例值 |
---|---|---|---|---|---|
biz_no | String | 是 | 9 | 商户号,9位数字组成的字符串 | 000001002(前6位机构号+3位扩展号) |
pay_type | String | 是 | 20 | 支付方式 | wechat.app |
format | String | 是 | 5 | JSON,XML | JSON |
charset | String | 是 | 10 | 请求参数的字符编码,特别对于product_name,product_desc可能含有中文的情况,需要先编码后,才能参与签名,UTF-8,GBK,GB2312 | UTF-8 |
sign_type | String | 是 | 10 | 签名类型,MD5,RSA | MD5 |
sign | String | 是 | 100 | 签名结果 | D2d9ac28ec72da9c612153c472c8fa814 |
timestamp | String | 是 | 14 | 发送请求时间,格式"yyyyMMddHHmmss" | 20170428130750 |
version | String | 是 | 5 | 调用接口的版本,固定为:1.0.0 | 1.0.0 |
notify_url | String | 是 | 200 | 服务器异步通知页面路径,支持HTTPS,不能带任何参数 | http://www.yoursite.com/notify_url |
page_url | String | 是 | 200 | 页面跳转同步通知页面路径,支持HTTPS,不能带任何参数(强校验,安安全性,正确性) | http://www.yoursite.com/page_url |
product_code | String | 是 | 10 | 产品编码 | BJHY,CJHY |
product_name | String | 是 | 128 | 商品名称,允许包含中文,不超过128个字符或者64个汉字 | XX会员 |
product_desc | String | 是 | 255 | 商品描述,允许包含中文,不超过255个字符或者127个汉字 | 买下载宝送XX会员活动 |
biz_order_no | String | 是 | 64 | 订单号,64个字符以内,可以包含字母、数字、下划线,保证商户端不重复 | 20170428010101001 |
timeout_express | String | 否 | 6 | 设置未付款交易的超时时间,一旦超时,该笔交易就会自动被关闭。当调用下单接口会触发即刻创建交易,此时开始计时。取值范围:1m~15d。m-分钟,h-小时,d-天,1c-当天(1c-当天的情况下,无论交易何时创建,都在0点关闭)。 该参数数值不接受小数点, 如 1.5h,可转换为 90m | 1.5h |
total_fee | int | 是 | - | 订单总金额,单位为分,非负整数 | 80 |
user_id | String | 是 | 64 | 迅雷uid | 126254863 |
passback_param | String | 是 | 512 | 公用回传参数,如果请求时传递了该参数,则返回给商户时会回传该参数。XX支付会在异步通知时将该参数原样返回。本参数必须进行UrlEncode之后才可以发送给支付网关 | {bizNo:"yueduvip",duration:1,productname:"XX会员"} |
extend_param | String | 是 | 512 | 不同支付方式业务扩展参数,具体参照不同渠道接口文档 | {card_no:"111",card_pwd:"111",card_amt:"50"} |
currency | int | 是 | 3 | 符合ISO 4217标准的三位字母代码,默认人民币:CNY 台币:TWD | CNY |
terminal_info | String | 是 | 255 | 终端信息,必备字段terminal_ip, user_agent | {terminal_ip:"114.114.114.114",user_agent:"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36"} |
响应参数
参数 | 类型 | 是否必填 | 最大长度 | 描述 | 实例值 |
---|---|---|---|---|---|
code | String | 是 | 5 | 网关返回码 | 10000 |
msg | String | 是 | 50 | 网关返回描述 | |
sub_code | String | 是 | 50 | 业务返回码 | |
sub_msg | String | 是 | 50 | 业务返回描述 | |
data | String | 否 | - | 各渠道用到的扩展返回值 | {order_no:"2017042811001004330000121536",code_url:"weixin://wxpay/s/An4baqw"} |
sign | String | 是 | 100 | 签名结果 | D2d9ac28ec72da9c612153c472c8fa814 |
对比
项目 | pay-gateway | payproxy4 | gateway |
---|---|---|---|
下单地址 | https://pay.xx.com/pub/order//pay | http://proxy.pay.xx.com/newPayHandle | http://pay.xx.com/gateway/newPayHandle |
业务号 | biz_no | bizNo | bizNo |
返回格式 | format | 无(仅支持xml) | 有(根据Content-Type) |
字符集 | charset | pageCharset(支持UTF-8,GBK,GB2312) | input_charset(未实现UTF-8,GBK,GB2312) |
签名类型 | sign_type | 无(固定MD5) | sign_type(仅支持MD5) |
签名值 | sign | signMsg | sign |
订单创建时间 | timestamp | orderTime | 无(利用now()) |
版本 | version(1.0.0) | version(v1.0) | version(2.0.0) |
通知地址 | notify_url | bgUrl(不支持HTTPS) | notify_url |
同步跳转地址 | page_url | fgUrl | page_url |
商品编码 | product_code | 无 | product_id |
商品名称 | product_name | productName | product_name |
商品描述 | product_desc | productDesc | product_desc |
订单号 | biz_order_no | orderId | biz_order_id |
交易超时时间 | timeout_express | 无 | 无 |
订单金额 | total_fee | orderAmt | order_amt |
用户id | user_id | xlnumId | xunlei_id |
公共回传参数 | passback_param | ext1,ext2 | extra_common_param |
业务扩展参数 | extend_param | other1,other2,other3 | extend_param |
币种 | currency | 无 | 无 |
终端信息 | terminal_info | clientIp,peerId | peer_id,client_ip |
支付
正式地址: https://pay.xx.com/pub/order/confirm
测试地址: https://pay.xx.com/test/order/confirm
请求参数
|参数|类型|是否必填|最大长度|描述|实例值|
|---|---|---|---|
|biz_no|String|是|9|商户号,9位数字组成的字符串|000001002(前6位机构号+3位扩展号)|
|format|String|是|5|JSON,XML|JSON|
|charset|String|是|10|请求参数的字符编码,特别对于product_name,product_desc可能含有中文的情况,需要先编码后,才能参与签名,UTF-8,GBK,GB2312|UTF-8|
|sign_type|String|是|10|签名类型,MD5,RSA|MD5|
|sign|String|是|100|签名结果|D2d9ac28ec72da9c612153c472c8fa814|
|timestamp|String|是|14|发送请求时间,格式"yyyyMMddHHmmss"|20170428130750|
|version|String|是|5|调用接口的版本,固定为:1.0.0|1.0.0|
|order_no|String|是|64|网关返回的订单号|2017042811001004330000121536|
|extend_param|String|是|512|不同支付方式业务扩展参数,具体参照不同渠道接口文档|{mobile:13560770129,verify_code:123456}|
响应参数
|参数|类型|是否必填|最大长度|描述|实例值|
|---|---|---|---|---|---|---|---|
|code|String|是|5|网关返回码|10000|
|msg|String|是|50|网关返回描述||
|sub_code|String|是|50|业务返回码||
|sub_msg|String|是|50|业务返回描述|
|data|String|否|-|各渠道用到的扩展返回值|{order_no:"2017042811001004330000121536",code_url:"weixin://wxpay/s/An4baqw"}|
|sign|String|是|100|签名结果|D2d9ac28ec72da9c612153c472c8fa814|
对比
项目 | pay-gateway | payproxy4 | gateway |
---|---|---|---|
接口地址 | https://pay.xx.com/pub/order//pay | /arSoftConfirmServlet | /arsoft/page |
商户号 | biz_no | 无 | 无 |
格式 | format | 无 | 无 |
字符集 | charset | 无 | 无 |
签名类型 | sign_type | 无 | 无 |
签名 | sign | signMsg | signMsg |
版本 | version | 无 | 无 |
时间 | timestamp | 无 | 无 |
订单号 | order_no | order_id | xlpayId |
业务方订单号 | 无 | trade_no | orderId |
扩展参数 | extend_param | verify_code | verify_code |
查询
正式地址: https://pay.xx.com/pub/order/query
测试地址: https://pay.xx.com/test/order/query
请求参数
参数 | 类型 | 是否必填 | 最大长度 | 描述 | 实例值 |
---|---|---|---|---|---|
biz_no | String | 是 | 9 | 商户号,9位数字组成的字符串 | 000001002(前6位机构号+3位扩展号) |
format | String | 是 | 5 | JSON,XML | JSON |
charset | String | 是 | 10 | 请求参数的字符编码,特别对于product_name,product_desc可能含有中文的情况,需要先编码后,才能参与签名,UTF-8,GBK,GB2312 | UTF-8 |
sign_type | String | 是 | 10 | 签名类型,MD5,RSA | MD5 |
sign | String | 是 | 100 | 签名结果 | D2d9ac28ec72da9c612153c472c8fa814 |
version | String | 是 | 5 | 调用接口的版本,固定为:1.0.0 | 1.0.0 |
order_no | String | 特殊可选 | 64 | 网关返回的订单号 | 2017042811001004330000121536 |
biz_order_no | String | 特殊可选 | 64 | 业务方的订单号 | 2017042811001004330000121536 |
响应参数
|参数|类型|是否必填|最大长度|描述|实例值|
|---|---|---|---|---|
|code|String|是|5|网关返回码|10000|
|msg|String|是|50|网关返回描述||
|sub_code|String|是|50|业务返回码||
|sub_msg|String|是|50|业务返回描述|
|data|String|否|-|各渠道用到的扩展返回值|{order_no:"2017042811001004330000121536",mobile:"13560770129",usershow:"paycenter010",order_status:"ORDER_CLOSE",total_fee:1500}|
|sign|String|是|100|签名结果|D2d9ac28ec72da9c612153c472c8fa814|
对比
项目 | pay-gateway | payproxy4 | gateway |
---|---|---|---|
接口地址 | https://pay.xx.com/pub/order//query | http://proxy.pay.xx.com/telemonthlyqueryServlet | /无 |
商户号 | biz_no | bizNo | 无 |
格式 | format | 无 | 无 |
字符集 | charset | 无 | 无 |
签名类型 | sign_type | 无 | 无 |
签名 | sign | signMsg | 无 |
时间 | timestamp | 无 | 无 |
版本 | version | 无 | 无 |
订单号 | order_no | 无 | 无 |
业务方订单号 | 无 | 无 | 无 |
用户id | 无(https://pay.xx.com/pub/contract//query) | userid | 无 |
取消订单(包月)
正式地址: https://pay.xx.com/pub/order/cancel
测试地址: https://pay.xx.com/test/order/cancel
退款
正式地址: https://pay.xx.com/pub/order/refund
测试地址: https://pay.xx.com/test/order/refund
回调
异步
地址 : notify_url
方式 : POST
触发条件:
- 支付成功
- 退款成功
|参数|类型|是否必填|最大长度|描述|实例值|
|---|---|---|---|
|notify_time|String|是|10|通知时间,格式"yyyyMMddHHmmss"|20170428130750|
|notify_type|int|是|-|通知类型,取值参见附录|order_status_sync|
|notify_id|String|是|-|通知校验ID(唯一性,顺序性)|ac05099524730693a8b330c5ecf72da9786|
|biz_no|String|是|10|商户号,10位数字组成的字符串|1234567890|
|charset|int|是|10|编码格式,如UTF-8、GBK、GB2312等与签名|UTF-8|
|version|String|是|5|调用接口的版本,固定为:1.0.0|1.0.0|
|sign_type|int|是|1|签名类型,MD5,RSA|MD5|
|sign|String|是|100|签名|DZXh8eeTuAHoYE3w1J+P|
|order_no|String|是|64|网关返回的订单号|2017042811001004330000121536|
|biz_order_no|String|是|64|业务方的订单号|2017042811001004330000121536|
|biz_refund_no|String|否|64|请求退款接口时,传入的退款请求号,如果在退款请求时未传入,则该值为创建交易时的业务订单号|201704HZ01RF001|
|user_id|String|是|64|用户在商户网站的用户id|126254863|
|order_status|String|是|64|交易状态,取值参见附录||
|total_fee|int|否|-|订单(退款)总金额,单位为分,非负整数|80|
|refund_fee|int|否|-|退款金额,单位为分,非负整数|80|
|currency|int|是|3|符合ISO 4217标准的三位字母代码,默认人民币:CNY 台币:TWD|CNY|
|passback_param|String|是|512|公用回传参数,如果请求时传递了该参数,则返回给商户时会回传该参数。 XX支付会在异步通知时将该参数原样返回。本参数必须进行UrlEncode之后才可以发送给支付网关|
|order_create_time|String|否|14|订单创建时间,格式"yyyyMMddHHmmss"|20170428130750|
|order_pay_time|String|否|14|订单支付时间,格式"yyyyMMddHHmmss"|20170428130750|
|order_refund_time|String|否|14|订单退款时间,格式"yyyyMMddHHmmss"|20170428130750|
注意:
- 程序执行完后必须打印输出“success”(不包含引号)。如果商户反馈给支付网关的字符不是success这7个字符,网关服务器会不断重发通知(通知的间隔频率一般是:1m,5m,10m,15m,30m,1h)
- 当商户收到服务器异步通知并打印出success时,服务器异步通知参数notify_id才会失效。也就是说在支付网关发送同一条异步通知时(包含商户并未成功打印出success导致支付网关重发数次通知),服务器异步通知参数notify_id是不变的
对比
项目 | pay-gateway | payproxy4 | gateway |
---|---|---|---|
通知时间 | notify_time | 无 | 无 |
通知类型 | notify_type | 无 | 无 |
通知id | notify_id | 无 | 无 |
商户号 | biz_no | 无 | 无 |
字符集 | charset | 无 | 无 |
版本 | version | version | version |
签名类型 | sign_type | 无 | 无 |
签名 | sign | signMsg | signMsg |
订单号 | order_no | xlpayId | xlpayId |
业务方订单号 | biz_order_no | orderId | orderId |
退款订单号 | biz_refund_no | 无 | 无 |
用户id | user_id | 无 | 无 |
订单状态 | order_status | payResult | payResult(固定值00,成功,失败无通知) |
订单金额 | total_fee | orderAmt | orderAmt |
退款金额 | refund_fee | 无 | 无 |
币种 | currency | 无 | 无 |
回传参数 | passback_param | ext1=ext1&ext2=ext2 | ext1=ext1&ext2=ext2 |
订单创建时间 | order_create_time | orderTime | orderTime |
订单支付时间 | order_pay_time | xlpayTime | xlpayTime |
订单退款时间 | order_refund_time | 无 | 无 |
订单错误码 | 无 | errCode固定值"" | errCode |
净收入 | 无 | fareamt | fareamt |
同步
跳转地址:
|项目|pay-gateway|payproxy4|gateway|
|---|---|---|---|---|
|同步跳转地址|?biz_no=&charset=&version=&sign_type=&sign=&biz_order_no=&order_no=&product_name=&user_id=&total_fee=¤cy=&order_status=&order_create_time=&order_pay_time=&passback_param=|?rtn=0&orderAmt=&orderId=&xunleiId=&productName=|?orderAmt=&bizOrderId=&userShow=&productName=|
附录
paytype
取值 | 含义 |
---|---|
wechat.app | 微信app |
wechat.office_accounts | 微信公众号 |
wechat.h5 | 微信H5 |
wechat.scancode | 微信扫码 |
wechat.monthly | 微信包月 |
alipay.app | 支付宝app |
alipay.scancode | 支付宝扫码 |
alipay.monthly | 支付宝包月 |
apple.pay | Apple Pay |
99bill.online_banking | 快钱网银 |
yeepay.online_banking | 易宝网银 |
tenpay.pay | 财付通支付中心 |
通知类型
取值 | 含义 |
---|---|
order_status_sync | 订单状态同步 |
交易状态
取值 | 含义 |
---|---|
order_success | 订单支付成功 |
order_finished | 订单结束 |
错误码
网关错误码
|code|msg|sub_code|sub_msg|解决方案|
|---|---|---|
|10000|接口调用成功,调用结果请参考具体的API文档所对应的业务返回参数|
|20000|服务不可用|gateway.unknow-error|服务暂不可用(网关自身错误)|稍后重试|
|20000|服务不可用|biz.unknow-error|服务暂不可用(业务系统不可用)|稍后重试|
|40001|缺少必要参数|gateway.missing-bizno|缺少业务号参数|检查请求参数,缺少bizno参数|
|40001|缺少必要参数|gateway.missing-format|缺少格式参数|检查请求参数,缺少format参数|
|40001|缺少必要参数|gateway.missing-charset|缺少字符集参数|检查请求参数,缺少charset参数|
|40001|缺少必要参数|gateway.missing-signtype|缺少签名类型参数|检查请求参数,缺少sign_type参数|
|40001|缺少必要参数|gateway.missing-sign|缺少签名参数|检查请求参数,缺少sign参数|
|40001|缺少必要参数|gateway.missing-timestamp|缺少订单时间参数|检查请求参数,缺少timestamp参数|。,
|40001|缺少必要参数|gateway.missing-version|缺少版本号参数|检查请求参数,缺少version参数|
|40001|缺少必要参数|gateway.missing-notifyurl|缺少回调通知参数|检查请求参数,缺少notify_url参数|
|40001|缺少必要参数|gateway.missing-pageurl|缺少同步跳转参数|检查请求参数,缺少page_url参数|
|40001|缺少必要参数|gateway.missing-productcode|缺少产品编码参数|检查请求参数,缺少product_code参数|
|40001|缺少必要参数|gateway.missing-productname|缺少产品名称参数|检查请求参数,缺少product_name参数|
|40001|缺少必要参数|gateway.missing-productdesc|缺少产品描述参数|检查请求参数,缺少product_desc参数|
|40001|缺少必要参数|gateway.missing-bizorderno|缺少渠道订单号参数|检查请求参数,缺少biz_order_no参数|
|40001|缺少必要参数|gateway.missing-totalfee|缺少订单金额参数|检查请求参数,缺少total_fee参数|
|40001|缺少必要参数|gateway.missing-userid|缺少用户uid参数|检查请求参数,缺少user_id参数|
|40001|缺少必要参数|gateway.missing-currency|缺少币种参数|检查请求参数,缺少currency参数|
|40001|缺少必要参数|gateway.missing-terminalinfo|缺少终端参数|检查请求参数,缺少terminal_info参数|
|40002|无效的参数|gateway.invalid-bizno|无效业务号参数|检查biz_no是否存在,或者审核通过|
|40002|无效的参数|gateway.invalid-format|无效格式参数|检查format参数,目前只有JSON和XML|
|40002|无效的参数|gateway.invalid-charset|无效字符集参数|检查charset参数,目前只有UTF-8,GBK,GB2312|
|40002|无效的参数|gateway.invalid-signtype|无效签名类型参数|检查sign_type参数,目前只有MD5,RSA|
|40002|无效的参数|gateway.invalid-sign|无效的签名参数|检查sign参数,可以用自助的签名工具对比|
|40002|无效的参数|gateway.invalid-timestamp|无效订单时间参数|检查timestamp参数,目前只支持与当前时刻相差30分钟内的订单|
|40002|无效的参数|gateway.invalid-version|无效版本号参数|检查version参数,目前只有1.0.0|
|40002|无效的参数|gateway.invalid-notifyurl|无效的回调通知参数|检查notify_url参数,不能带有参数,满足网址格式|
|40002|无效的参数|gateway.invalid-pageurl|无效同步跳转参数|检查page_url参数,不能带有参数,满足网址格式|
|40002|无效的参数|gateway.invalid-productcode|无效的产品编码参数|检查product_code参数,目前已有的BJHY(白金会员),CJHY(超级会员)|
|40002|无效的参数|gateway.invalid-productname|无效产品名称参数|检查product_name参数,是否含有乱码,长度是否超过|
|40002|无效的参数|gateway.invalid-productdesc|无效产品描述参数|检查product_desc参数,是否含有乱码,长度是否超过|
|40002|无效的参数|gateway.invalid-bizorderno|无效渠道订单号参数|检查biz_order_no参数,是否超过长度|
|40002|无效的参数|gateway.invalid-totalfee|无效订单金额参数|检查total_fee参数,人名币最大100000000分|
|40002|无效的参数|gateway.invalid-userid|无效用户uid参数|检查user_id参数,是否存在|
|40002|无效的参数|gateway.invalid-currency|无效币种参数|检查currency参数,是否符合ISO 4217标准的三位字母代码,默认人民币:CNY 台币:TWD|
|40002|无效的参数|gateway.invalid-terminalinfo|无效终端参数|检查terminal_info参数,是否含有必要参数terminal_ip, user_agent|
|40004|业务处理失败|对应业务错误码,明细错误码和解决方案请参考具体渠道的API接口文档|
例如:微信扫码业务错误码
|40004|业务处理失败|NOAUTH|商户无此接口权限|请商户前往申请此接口权限|
|---|---|---|
|40004|业务处理失败|ORDERPAID|订单已支付|请商请确认该订单号是否重复支付,如果是新单,请使用新订单号提交|
|40004|业务处理失败|ORDERCLOSED|订单已关闭|请商商户订单号异常,请重新下单支付|
|40004|业务处理失败|SYSTEMERROR|系统错误|系统异常,请用相同参数重新调用|
评论区