侧边栏壁纸
  • 累计撰写 39 篇文章
  • 累计创建 1 个标签
  • 累计收到 3 条评论
标签搜索

【深入浅出-行业分享】(2):新支付网关协议

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

下单接口

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

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

请求方式: POST

请求参数

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

响应参数

参数类型是否必填最大长度描述实例值
codeString5网关返回码10000
msgString50网关返回描述
sub_codeString50业务返回码
sub_msgString50业务返回描述
dataString-各渠道用到的扩展返回值{order_no:"2017042811001004330000121536",code_url:"weixin://wxpay/s/An4baqw"}
signString100签名结果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_codeproduct_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_noString9商户号,9位数字组成的字符串000001002(前6位机构号+3位扩展号)
formatString5JSON,XMLJSON
charsetString10请求参数的字符编码,特别对于product_name,product_desc可能含有中文的情况,需要先编码后,才能参与签名,UTF-8,GBK,GB2312UTF-8
sign_typeString10签名类型,MD5,RSAMD5
signString100签名结果D2d9ac28ec72da9c612153c472c8fa814
versionString5调用接口的版本,固定为: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

评论区