侧边栏壁纸
博主头像
mousycoder博主等级

  • 累计撰写 39 篇文章
  • 累计创建 1 个标签
  • 累计收到 3 条评论
标签搜索
【深入浅出-行业分享】

【深入浅出-行业分享】（2）：新支付网关协议

mousycoder
mousycoder
2019-06-01 / 0 评论 / 0 点赞 / 218 阅读 / 11,316 字
温馨提示：
本文最后更新于 2022-01-21，若内容或图片失效，请留言反馈。部分素材来自网络，若不小心影响到您的利益，请联系我们删除。

下单接口

正式地址： https://pay.xx.com/pub/order/pay

测试地址： https://pay.xx.com/test/order/pay

请求方式: POST

请求参数

参数类型是否必填最大长度描述实例值
biz_noString是9商户号，9位数字组成的字符串000001002(前6位机构号+3位扩展号)
pay_typeString是20支付方式wechat.app
formatString是5JSON,XMLJSON
charsetString是10请求参数的字符编码,特别对于product_name,product_desc可能含有中文的情况，需要先编码后，才能参与签名,UTF-8,GBK,GB2312UTF-8
sign_typeString是10签名类型，MD5,RSAMD5
signString是100签名结果D2d9ac28ec72da9c612153c472c8fa814
timestampString是14发送请求时间，格式"yyyyMMddHHmmss"20170428130750
versionString是5调用接口的版本，固定为:1.0.01.0.0
notify_urlString是200服务器异步通知页面路径,支持HTTPS,不能带任何参数http://www.yoursite.com/notify_url
page_urlString是200页面跳转同步通知页面路径,支持HTTPS,不能带任何参数(强校验，安安全性，正确性)http://www.yoursite.com/page_url
product_codeString是10产品编码BJHY,CJHY
product_nameString是128商品名称,允许包含中文,不超过128个字符或者64个汉字XX会员
product_descString是255商品描述,允许包含中文,不超过255个字符或者127个汉字买下载宝送XX会员活动
biz_order_noString是64订单号，64个字符以内，可以包含字母、数字、下划线，保证商户端不重复20170428010101001
timeout_expressString否6设置未付款交易的超时时间，一旦超时，该笔交易就会自动被关闭。当调用下单接口会触发即刻创建交易，此时开始计时。取值范围：1m～15d。m-分钟，h-小时，d-天，1c-当天（1c-当天的情况下，无论交易何时创建，都在0点关闭）。 该参数数值不接受小数点， 如 1.5h，可转换为 90m1.5h
total_feeint是-订单总金额，单位为分,非负整数80
user_idString是64迅雷uid126254863
passback_paramString是512公用回传参数，如果请求时传递了该参数，则返回给商户时会回传该参数。XX支付会在异步通知时将该参数原样返回。本参数必须进行UrlEncode之后才可以发送给支付网关{bizNo:"yueduvip",duration:1,productname:"XX会员"}
extend_paramString是512不同支付方式业务扩展参数,具体参照不同渠道接口文档{card_no:"111",card_pwd:"111",card_amt:"50"}
currencyint是3符合ISO 4217标准的三位字母代码，默认人民币：CNY 台币：TWDCNY
terminal_infoString是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"}

响应参数

参数类型是否必填最大长度描述实例值
codeString是5网关返回码10000
msgString是50网关返回描述
sub_codeString是50业务返回码
sub_msgString是50业务返回描述
dataString否-各渠道用到的扩展返回值{order_no:"2017042811001004330000121536",code_url:"weixin：//wxpay/s/An4baqw"}
signString是100签名结果D2d9ac28ec72da9c612153c472c8fa814

对比

项目pay-gatewaypayproxy4gateway
下单地址https://pay.xx.com/pub/order//payhttp://proxy.pay.xx.com/newPayHandlehttp://pay.xx.com/gateway/newPayHandle
业务号biz_nobizNobizNo
返回格式format无(仅支持xml)有(根据Content-Type)
字符集charsetpageCharset(支持UTF-8,GBK,GB2312)input_charset(未实现UTF-8,GBK,GB2312)
签名类型sign_type无(固定MD5)sign_type(仅支持MD5)
签名值signsignMsgsign
订单创建时间timestamporderTime无(利用now())
版本version(1.0.0)version(v1.0)version(2.0.0)
通知地址notify_urlbgUrl(不支持HTTPS)notify_url
同步跳转地址page_urlfgUrlpage_url
商品编码product_code无product_id
商品名称product_nameproductNameproduct_name
商品描述product_descproductDescproduct_desc
订单号biz_order_noorderIdbiz_order_id
交易超时时间timeout_express无无
订单金额total_feeorderAmtorder_amt
用户iduser_idxlnumIdxunlei_id
公共回传参数passback_paramext1,ext2extra_common_param
业务扩展参数extend_paramother1,other2,other3extend_param
币种currency无无
终端信息terminal_infoclientIp,peerIdpeer_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-gatewaypayproxy4gateway
接口地址https://pay.xx.com/pub/order//pay/arSoftConfirmServlet/arsoft/page
商户号biz_no无无
格式format无无
字符集charset无无
签名类型sign_type无无
签名signsignMsgsignMsg
版本version无无
时间timestamp无无
订单号order_noorder_idxlpayId
业务方订单号无trade_noorderId
扩展参数extend_paramverify_codeverify_code

查询

正式地址： https://pay.xx.com/pub/order/query

测试地址： https://pay.xx.com/test/order/query

请求参数

参数类型是否必填最大长度描述实例值
biz_noString是9商户号，9位数字组成的字符串000001002(前6位机构号+3位扩展号)
formatString是5JSON,XMLJSON
charsetString是10请求参数的字符编码,特别对于product_name,product_desc可能含有中文的情况，需要先编码后，才能参与签名,UTF-8,GBK,GB2312UTF-8
sign_typeString是10签名类型，MD5,RSAMD5
signString是100签名结果D2d9ac28ec72da9c612153c472c8fa814
versionString是5调用接口的版本，固定为:1.0.01.0.0
order_noString特殊可选64网关返回的订单号2017042811001004330000121536
biz_order_noString特殊可选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-gatewaypayproxy4gateway
接口地址https://pay.xx.com/pub/order//queryhttp://proxy.pay.xx.com/telemonthlyqueryServlet/无
商户号biz_nobizNo无
格式format无无
字符集charset无无
签名类型sign_type无无
签名signsignMsg无
时间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

触发条件：

  1. 支付成功
  2. 退款成功

|参数|类型|是否必填|最大长度|描述|实例值|
|---|---|---|---|
|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|

注意：

  1. 程序执行完后必须打印输出“success”（不包含引号）。如果商户反馈给支付网关的字符不是success这7个字符，网关服务器会不断重发通知（通知的间隔频率一般是：1m,5m,10m,15m,30m,1h）
  2. 当商户收到服务器异步通知并打印出success时，服务器异步通知参数notify_id才会失效。也就是说在支付网关发送同一条异步通知时（包含商户并未成功打印出success导致支付网关重发数次通知），服务器异步通知参数notify_id是不变的

对比

项目pay-gatewaypayproxy4gateway
通知时间notify_time无无
通知类型notify_type无无
通知idnotify_id无无
商户号biz_no无无
字符集charset无无
版本versionversionversion
签名类型sign_type无无
签名signsignMsgsignMsg
订单号order_noxlpayIdxlpayId
业务方订单号biz_order_noorderIdorderId
退款订单号biz_refund_no无无
用户iduser_id无无
订单状态order_statuspayResultpayResult(固定值00，成功，失败无通知)
订单金额total_feeorderAmtorderAmt
退款金额refund_fee无无
币种currency无无
回传参数passback_paramext1=ext1&ext2=ext2ext1=ext1&ext2=ext2
订单创建时间order_create_timeorderTimeorderTime
订单支付时间order_pay_timexlpayTimexlpayTime
订单退款时间order_refund_time无无
订单错误码无errCode固定值""errCode
净收入无fareamtfareamt

同步

跳转地址：

|项目|pay-gateway|payproxy4|gateway|
|---|---|---|---|---|
|同步跳转地址|?biz_no=&charset=&version=&sign_type=&sign=&biz_order_no=&order_no=&product_name=&user_id=&total_fee=&currency=&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.payApple 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|系统错误|系统异常，请用相同参数重新调用|

0
版权归属： mousycoder
本文链接： http://mousycoder.com/2019/06/01/thinking-in-sharing-3
许可协议： 本文使用《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》协议授权

评论区