weiXin

来自于:官方

registerApp sendRequest auth cancelAuth getUserInfo refreshToken

概述

weiXin封装了微信开放平台的SDK,使用此模块可轻松实现分享消息到微信客户端的功能。 本模块集成了微信支付功能,兼容v2、v3版本支付账号。v2版本支付功能分三步:1,getToken获取token;2,getOrder获取预支付订单号;3,payOrder支付。v2版本前两部可在服务器端完成,得到正确的参数后直接调用第三步的接口。注意签名过程必须在服务器端完成。V3版本支付功能有两套支付方案,方案一:同v2支付流程,与v2不同的是参数生成规范、签名规范(参考微信支付官方文档);方案二:首先调用config接口配置支付参数(亦可通过key.xml配置相关支付参数,key.xml配置方法见下文),其次调用pay接口去支付。本支付方案签名过程是在模块内处理,微信官方建议获取预支付订单号和签名都在服务器端处理,所以建议大家采用方案一支付方式。

此模块已拆分为 wx(分享、登录功能)和 wxPay(支付功能)模块。建议使用 优化版的 wx 和 wxPay,此模块已停止更新。

使用此模块之前需先配置config文件的Feature,方法如下

  • 名称:weiXin
  • 参数:urlScheme、apiKey、apiSecret
  • 描述:配置微信专用的URL Scheme,使得本应用可以启动微信客户端,并与之交换数据,同时可以从微信客户端返回到本应用,注意微信的urlScheme既是apikey(appid)。urlScheme为必须配置字段,apiKey和apiSecret为选择配置字段。
  • 配置示例:
  1. <feature name="weiXin">
  2. <param name="urlScheme" value="wxd0d84bbf23b4a0e4"/>
  3. <param name="apiKey" value="wxd0d84bbf23b4a0e4"/>
  4. <param name="apiSecret" value="a354f72aa1b4c2b8eaad137ac81434cd"/>
  5. </feature>
  • 字段描述:

param-urlScheme:通过微信开放平台申请的appid(apiKey)

param-apiKey:通过微信开放平台申请的appid(apiKey),调用分享功能和支付功能使用到的参数

param-apiSecret 通过微信开放平台申请的secret,调用支付功能使用到的参数

key.xml文档配置详解: key.xml文件需要放在widget/res文件目录下,其内容格式如下:

  1. <?xml version="1.0" encoding="UTF-8" ?>
  2. <security>
  3. <item name="weiXin_pay_appId" value="wxd0d84bbf23b4a0e4"/>
  4. <item name="weiXin_pay_mchId" value="1234567890"/>
  5. <item name="weiXin_pay_partnerKey" value="***"/>
  6. <item name="weiXin_pay_notifyUrl" value="***"/>
  7. <item name="其它服务需加密的参数配置 " value="***"/>
  8. .
  9. .
  10. .
  11. </security>
  • weiXin_pay_appId: //在微信开发者平台创建应用生成的appId
  • weiXin_pay_mchId: //商户号,填写商户对应参数
  • weiXin_pay_partnerKey: //商户API密钥,填写相应参数
  • weiXin_pay_notifyUrl: //支付结果回调页面

Android 系统平台上需注意事项请参考微信集成注意事项 weiXin - 图1 weiXin - 图2

registerApp

注册应用

registerApp({params}, callback(ret, err))

params

key:

  • 类型:字符串
  • 默认值:无
  • 描述:微信开放平台获取的key,可为空,若为空则从当前widget内config文件读取

secret:

  • 类型:字符串
  • 默认值:无
  • 描述:微信开放平台获的secret,可为空,若为空则从当前widget内config文件读取

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status:true //操作成功状态值
  3. }

err:

  • 类型:JSON 对象

内部字段:

  1. {
  2. code:0 //错误码
  3. msg:"" //错误描述
  4. }

示例代码

  1. var weiXin = api.require('weiXin');
  2. weiXin.registerApp(
  3. function(ret, err) {
  4. if (ret.status) {
  5. api.alert({ msg: '' + ret.status });
  6. } else {
  7. api.alert({ msg: err.msg });
  8. }
  9. }
  10. );

补充说明

注册应用

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

sendRequest

发表内容

sendRequest({params}, callback(ret, err))

params

scene:

  • 类型:字符串
  • 默认值:timeline
  • 描述:场景(详见场景常量),不能为空

contentType:

  • 类型:字符串
  • 默认值:无
  • 描述:发表内容类型(详见内容类型常量),不能为空

title:

  • 类型:字符串
  • 默认值:无
  • 描述:标题,不能为空。当contentType为text时,该字段将被忽略

description:

  • 类型:字符串
  • 默认值:无
  • 描述:内容,不能为空

thumbUrl:

  • 类型:字符串
  • 默认值:无
  • 描述:缩略图本地url地址,不能为空

contentUrl:

  • 类型:字符串
  • 默认值:无
  • 描述:内容url地址,只有contentType为text时可以为空

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. status:true //操作成功状态值
  3. }

err:

  • 类型:JSON 对象

内部字段:

  1. {
  2. code:0 //错误码(详见错误码常量)
  3. msg: "" //错误描述
  4. }

示例代码

  1. //内容类型为music或video时,内容地址应为流媒体地址;
  2. var weiXin = api.require('weiXin');
  3. weiXin.sendRequest({
  4. scene: 'timeline',
  5. contentType: 'music',
  6. title: '测试用标题',
  7. description: '测试用内容',
  8. thumbUrl: 'fs://a.png',
  9. contentUrl: 'http://117.78.5.26/files/shijian.mp3'
  10. }, function(ret, err) {
  11. if (ret.status) {
  12. api.alert({ title: '发表微信', msg: '发表成功', buttons: ['确定'] });
  13. } else {
  14. api.alert({
  15. title: '发表失败',
  16. msg: err.msg,
  17. buttons: ['确定']
  18. });
  19. }
  20. });
  21. //内容类型为web_page时,内容地址为常规网址;
  22. var weiXin = api.require('weiXin');
  23. weiXin.sendRequest({
  24. scene: 'timeline',
  25. contentType: 'web_page',
  26. title: '测试用标题',
  27. description: '测试用内容',
  28. thumbUrl: 'fs://a.png',
  29. contentUrl: 'http://www.baidu.com/'
  30. }, function(ret, err) {
  31. if (ret.status) {
  32. api.alert({ title: '发表微信', msg: '发表成功', buttons: ['确定'] });
  33. } else {
  34. api.alert({ title: '发表失败', msg: err.msg, buttons: ['确定'] });
  35. }
  36. });

补充说明

暂不支持视频流地址;title字段在contentType为text时不起作用。每个窗口内必须在registerApp接口后使用

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

auth

登录授权获取token

auth(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. status:true //操作成功状态值
  3. token //登录成功获取的token值,字符串类型,初次登陆有效期2小时,刷新token后有效期为30天
  4. }

err:

  • 类型:JSON 对象

内部字段:

  1. {
  2. msg:"" //错误描述
  3. }

示例代码

  1. var weiXin = api.require('weiXin');
  2. weiXin.auth(function(ret, err) {
  3. if (ret.status) {
  4. api.alert({ msg: ret.token });
  5. } else {
  6. api.alert({ msg: err.msg });
  7. }
  8. });

补充说明

调用此接口前应确保调用过一次registerApp接口,此接口需要访问网络,所以需要一段时间才能callBack得到token

可用性

iOS系统,Android系统 可提供的1.0.2及更高版本

cancelAuth

取消登录授权,删除本地记录的token

cancelAuth(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. status: //操作成功状态值,布尔类型
  3. }

err:

  • 类型:JSON 对象

内部字段:

  1. {
  2. msg:"" //错误描述
  3. }

示例代码

  1. var weiXin = api.require('weiXin');
  2. weiXin.cancelAuth(function(ret, err) {
  3. if (ret.status) {
  4. api.alert({ msg: '退出成功' });
  5. } else {
  6. api.alert({ msg: err.msg });
  7. }
  8. });

补充说明

可用性

iOS系统,Android系统

可提供的1.0.2及更高版本

getUserInfo

获取用户信息

getUserInfo(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. status: //操作成功状态值,布尔类型
  3. openid: //普通用户的标识,对当前开发者帐号唯一
  4. nickname: //普通用户昵称
  5. sex: //普通用户性别,1为男性,2为女性
  6. province: //普通用户个人资料填写的省份
  7. city: //普通用户个人资料填写的城市
  8. country: //国家,如中国为CN
  9. headimgurl: //用户头像,最后一个数值代表正方形头像大小(有0、46、64、96、132数值可选,0代表640*640正方形头像),//用户没有头像时该项为空
  10. privilege: //用户特权信息,json数组,如微信沃卡用户为(chinaunicom)
  11. unionid: //用户统一标识。针对一个微信开放平台帐号下的应用,同一用户的unionid是唯一的。
  12. }

err:

  • 类型:JSON 对象

内部字段:

  1. {
  2. msg:"" //错误描述
  3. }

示例代码

  1. var weiXin = api.require('weiXin');
  2. weiXin.getUserInfo(function(ret, err) {
  3. if (ret.status) {
  4. api.alert({ msg: '获取成功' });
  5. } else {
  6. api.alert({ msg: err.msg });
  7. }
  8. });

补充说明

调用此接口前确保已经登录

可用性

iOS系统,Android系统

可提供的1.0.2及更高版本

refreshToken

token过期时调用此接口刷新token

refreshToken(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. status: //操作成功状态值,布尔类型
  3. token //登录成功获取的token值,字符串类型,有效期30天
  4. }

err:

  • 类型:JSON 对象

内部字段:

  1. {
  2. msg:"" //错误描述
  3. }

示例代码

  1. var weiXin = api.require('weiXin');
  2. weiXin.refreshToken(function(ret, err) {
  3. if (ret.status) {
  4. api.alert({ msg: '刷新成功' });
  5. } else {
  6. api.alert({ msg: err.msg });
  7. }
  8. });

补充说明

调用此接口前,确保已经登录过

可用性

iOS系统,Android系统

可提供的1.0.2及更高版本

getToken getOrder payOrder config pay

准备工作

在使用接口之前请先保证持有向微信开放平台申请得到的 appid、appsecret(长度为32 的字符串,用于获取 access_token)、appkey(长度为 128 的字符串,用于支付过程中生 成 app_signature。针对v2版支付账号)及 partnerkey(微信公众平台商户模块生成的商户密钥)。v3版支付账号请按照微信官方文档说明的签名方式把getToken和getOrder放在服务器端执行。

getToken

获取支付token

getToken({params}, callback(ret, err))

params

key:

  • 类型:字符串
  • 默认值:无
  • 描述:微信开放平台获取的key,可为空,若为空则使用registerApp接口传入的key,若registerApp接口没有传key参数,则从当前widget内config文件读取

secret:

  • 类型:字符串
  • 默认值:无
  • 描述:微信开放平台获的secret,可为空,若为空则使用registerApp接口传入的secret,若registerApp接口没有传secret参数,则从当前widget内config文件读取

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. status: //操作成功状态值
  3. token: //返回的token值
  4. expires: //token过期时间
  5. }

err:

  • 类型:JSON 对象

内部字段:

  1. {
  2. msg:"" //错误描述
  3. }

示例代码

  1. var weiXin = api.require('weiXin');
  2. weiXin.getToken({
  3. key: 'wx652070b3a10fcd45',
  4. secret: '00f373c57777e46ba86d461cbcc2fbe8'
  5. }, function(ret, err) {
  6. if (ret.status) {
  7. var token = ret.token;
  8. var expires = ret.expires;
  9. } else {
  10. api.alert({ msg: err.msg });
  11. }
  12. });

补充说明

获取支付的token

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getOrder

获取预支付订单

getOrder({params}, callback(ret, err))

params

token:

  • 类型:字符串
  • 默认值:无
  • 描述:上个接口获取到的token,不能为空

orderInfo:

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. status: //操作成功状态值
  3. orderId: //返回的订单号
  4. }

err:

  • 类型:JSON 对象

内部字段:

  1. {
  2. msg:"" //错误描述
  3. }

示例代码

  1. var weiXin = api.require('weiXin');
  2. weiXin.getOrder({
  3. token: '',
  4. orderInfo: ''
  5. }, function(ret, err) {
  6. if (ret.status) {
  7. var orderId = ret.orderId;
  8. } else {
  9. api.alert({ msg: err.msg });
  10. }
  11. });

补充说明

生成支付的订单号

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

payOrder

支付订单

payOrder({params}, callback(ret, err))

params

secret:

  • 类型:字符串
  • 默认值:无
  • 描述:商家从微信开放平台申请的secret,可为空,若为空则使用registerApp接口或者getToken接口传入的secret,若registerApp接口和getToken接口都没有传secret参数,则从当前widget内config文件读取

key:

  • 类型:字符串
  • 默认值:无
  • 描述:从微信开放平台获取的key,可为空,若为空则使用registerApp接口或者getToken接口传入的key,若registerApp接口和getToken接口都没有传key参数,则从当前widget内config文件读取

orderId:

  • 类型:字符串
  • 默认值:无
  • 描述:上个接口生成的订单号,不能为空

partnerId:

  • 类型:字符串
  • 默认值:无
  • 描述:商家和微信合作的id号,审核通过后微信发送到商家邮箱,不能为空

nonceStr:

  • 类型:字符串
  • 默认值:无
  • 描述:随机串,防重发,不能为空

timeStamp:

  • 类型:字符串
  • 默认值:无
  • 描述:时间戳,防重发,不能为空

package:

  • 类型:字符串
  • 默认值:无
  • 描述:商家根据财付通文档填写的数据和签名(详情见支付注意事项),不能为空

sign:

  • 类型:字符串
  • 默认值:无
  • 描述:商家根据微信开放平台文档对数据做的签名(详情见支付注意事项),不能为空

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. status: //操作成功状态值
  3. result: //返回的支付结果
  4. }

err:

  • 类型:JSON 对象

内部字段:

  1. {
  2. msg:"" //错误描述
  3. }

示例代码

  1. var weiXin = api.require('weiXin');
  2. weiXin.payOrder({
  3. orderId: '',
  4. partnerId: '',
  5. nonceStr: '',
  6. timeStamp: '',
  7. package: '',
  8. sign: ''
  9. }, function(ret, err) {
  10. if (ret.status) {
  11. } else {
  12. api.alert({ msg: err.msg });
  13. }
  14. });

补充说明

支付订单

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

config

v3版支付账号配置商户支付参数

config({params}, callback(ret, err))

params

appId:

  • 类型:字符串
  • 默认值:无
  • 描述(可选项)在微信开发者平台创建应用生成的appId
  • 备注:若不传或者传空则从key.xml文件读取相应字段信息

mchId:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)商户号,填写商户对应参数
  • 备注:若不传或者传空则从key.xml文件读取相应字段信息

partnerKey:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)商户API密钥,填写相应参数
  • 备注:若不传或者传空则从key.xml文件读取相应字段信息

notifyUrl:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)支付结果回调页面
  • 备注:若不传或者传空则从key.xml文件读取相应字段信息

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: //操作成功状态值
  3. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. msg:"" //错误描述
  3. }

示例代码

  1. var weiXin = api.require('weiXin');
  2. weiXin.config({
  3. appId: '',
  4. mchId: '',
  5. partnerKey: '',
  6. notifyUrl: ''
  7. }, function(ret, err) {
  8. if (ret.status) {
  9. ret.result;
  10. } else {
  11. api.alert({ msg: err.msg });
  12. }
  13. });

补充说明

配置商家支付信息,v3版本以上支付账号适用

可用性

iOS系统,Android系统

可提供的1.0.1及更高版本

pay

v3版支付账号支付订单

pay({params}, callback(ret, err))

params

body:

  • 类型:字符串
  • 默认值:无
  • 描述:商品或支付单简要描述

totalFee:

  • 类型:字符串
  • 默认值:无
  • 描述:订单总金额,只能为整数,单位(分)

tradeNo:

  • 类型:字符串
  • 默认值:无
  • 描述:商户系统内部的订单号,32个字符内、可包含字母, 其他说明见商户订单号

spBillCreateIp:

  • 类型:字符串
  • 默认值:196.168.1.1
  • 描述:(可选项)APP和网页支付提交用户端ip,Native支付填调用微信支付API的机器IP

deviceInfo:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)终端设备号(门店号或收银设备ID),注意:PC网页或公众号内支付请传”WEB”
  • 备注:可不传

detail:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)商品名称明细列表

attach:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)附加数据,在查询API和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据

feeType:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型

timeStart:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)订单生成时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则

timeExpire:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)订单失效时间,格式为yyyyMMddHHmmss,如2009年12月27日9点10分10秒表示为20091227091010。其他详见时间规则

goodsTag:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)商品标记,代金券或立减优惠功能的参数,说明详见代金券或立减优惠

productId:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)trade_type=NATIVE,此参数必传。此id为二维码中包含的商品ID,商户自行定义

openId:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)trade_type=JSAPI,此参数必传,用户在商户appid下的唯一标识。下单前需要调用【网页授权获取用户信息】接口获取到用户的Openid

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. status: //操作成功状态值
  3. result: //返回的支付结果
  4. }

err:

  • 类型:JSON 对象
  • 内部字段:
  1. {
  2. msg:"" //错误描述
  3. }

示例代码

  1. var weiXin = api.require('weiXin');
  2. weiXin.pay({
  3. body: '如意金箍棒',
  4. totalFee: '10',
  5. tradeNo: '1234567890abcdefghiglmnopqrstuvw'
  6. }, function(ret, err) {
  7. if (ret.status) {
  8. ret.result;
  9. } else {
  10. api.alert({ msg: err.msg });
  11. }
  12. });

补充说明

支付订单。,v3版本以上支付账号适用

可用性

iOS系统,Android系统

可提供的1.0.1及更高版本

场景 内容类型 错误码 订单详情生成 支付注意事项

场景

场景

取值范围:

  • session //会话
  • timeline //朋友圈
  • favorite //收藏

内容类型

内容类型

取值范围:

  • text //文本
  • image //图片
  • music //音乐
  • video //视频
  • web_page //网页

错误码

错误类型

取值范围:

  • -1 //当前设备未安装微信客户端
  • 0 //没有错误
  • 1 //普通错误
  • 2 //用户取消
  • 3 //发送失败
  • 4 //授权拒绝
  • 5 //不支持

订单详情生成

订单详情是json格式的字符串,示例如下:

  1. {
  2. "appid":"wwwwb4f85f3a797777",
  3. "traceid":"crestxu",
  4. "noncestr":"111112222233333", "package":"bank_type=WX&body=XXX&fee_type=1&input_charset=GBK&notify_url=http%3a%2 f%2f www.qq.com&out_trade_no=16642817866003386000&partner=1900000109&spbill_create_ip=1 27.0.0.1&total_fee=1&sign=BEEF37AD19575D92E191C1E4B1474CA9",
  5. "timestamp":1381405298, "app_signature":"53cca9d47b883bd4a5c85a9300df3da0cb48565c",
  6. "sign_method":"sha1"
  7. }

其中,各字段含义如下:

参数是否必须说明
appid应用唯一标识,在微信开放平台提交应用审核通过后获得
traceid商家对用户的唯一标识,如果用微信sso,此处建议填写授权用户的openid
noncestr32位内的随机串,防重发
package订单详情(具体方法见后文)
timestamp时间戳,为1970念1月1日00:00到请求发起时间的秒数
app_signature签名(具体生成方法见后文)
Sign_method加密方式,默认为sha1

package 生成方法:

  1. 对所有传入参数按照字段名的 ASCII 码从小到大排序(字典序)后,使用 URL 键值对的格 式(即 key1=value1&key2=value2…)拼接成字符串 string1;
  2. 在 string1 最后拼接上 key=partnerKey 得到 stringSignTemp 字符串, 并对 stringSignTemp 进行 md5 运算,再将得到的字符串所有字符转换为大写,得到 sign 值 signValue;
  3. 对 string1 中的所有键值对中的 value 进行 urlencode 转码,按照 a 步骤重新拼接成字符 串,得到 string2。对于 js 前端程序,一定要使用函数 encodeURIComponent 进行 urlencode 编码(注意!进行 urlencode 时要将空格转化为%20 而不是+);
  4. 将 sign=signValue 拼接到 string1 后面得到最终的 package 字符串;

app_signature 生成方法:

  1. 参与签名的字段包括:appid、appkey、noncer、package、timestamp 以及 traceid;
  2. 对所有待签名参数按照字段名的 ASCII 码从小到大排序(字典序)后,使用 URL 键值对的 格式(即 key1=value1&key2=value2…)拼接成字符串 string1。 注意:所有参数名均为小写字符;
  3. 对 string1 作签名算法,字段名和字段值都采用原始值,不进行 URL 转义。具体签名算法 为 SHA1;

支付注意事项

调起微信支付 SDK 时,请求参数中 package 需填写为:Sign=WXPay

注意:不能写在客户端,这个过程应都由服务器端完成