CCBLife小程序API使用说明_v1.1_20230511

文档修订记录

版本日期修订说明
1.02023.02.14同步在线文档接口说明
1.12023.05.11新增实名认证api

文档目录

1. 文档说明

本文档所描述API适用于建行生活App端内运行的JUMP小程序。

2. 接口说明

回调函数统一格式:

回调结果参数(Object res)

属性类型说明最低版本
dataobject返回内容-
statestring状态码-
msgstring状态信息|报错信息-

响应内容封装在data的Json对象里

2.1 login

用途说明

登录|获取用户信息。提供客户端认证模式与服务端认证模式两种模式。若建行生活处于未登录状态会跳转建行生活APP的登录页进行登录(行内单点登录使用)。

请求参数

属性类型默认值必填说明最低版本
typenumber-登录类型-
PLATFORM_IDstring--服务方ID-
Opn_Chnl_IDstring-合作方渠道编号-
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

type 的合法值:

说明最低版本
0客户端认证模式-
1服务端认证模式-

响应内容

属性类型说明最低版本
encryptedDatastring"userid=xxx&mobile=xxx&PreAhr_ID=xxx"的加密字符串。(userid:建行生活用户编号,mobile:手机号,PreAhr_ID:用户中心预授权编码)-

注意

2.2 ccblife_login

用途说明

登录|获取用户信息。提供客户端认证模式与服务端认证模式两种模式。若建行生活处于未登录状态会跳转建行生活APP的登录页进行登录。

请求参数

属性类型默认值必填说明最低版本
typenumber-登录类型-
PLATFORM_IDstring--服务方ID-
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

type 的合法值:

说明最低版本
0客户端认证模式-
1服务端认证模式-

响应内容

属性类型说明最低版本
encryptedDatastring"unionid=xxx&phone=xxx&locationCityCode=xxx"的加密字符串。(unionid:建行生活用户编号,phone:手机号,locationCityCode:用户选择城市码)-

注意

2.3 checkSession

用途说明

检查登录态是否过期。

请求参数

属性类型默认值必填说明最低版本
PLATFORM_IDstring--服务方ID-
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

响应内容

属性类型说明最低版本
isVaildboolean登录态是否有效-

2.4 getUserInfo

用途说明

获取用户信息。目前能返回的信息均为登录态敏感信息,加密。

请求参数

属性类型默认值必填说明最低版本
withCredentialsbooleantrue是否带上登录态信息。-
loginTypenumber-当前登录类型-
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

loginType的合法值:

说明最低版本
0客户端认证模式-
1服务端认证模式-

响应内容

state的合法值:

说明最低版本
0获取成功-
1获取失败-
2获取失败:未授权-

data:

属性类型说明最低版本
userInfoObject用户信息,不包含敏感数据-
encryptedDatastring包括敏感数据在内的完整用户信息的加密数据-
signaturestring用户数据签名-
saltstring签名使用的字符串-
ivstring加密算法的初始向量-

encryptedData 解密:

属性类型说明最低版本
unionidstring建行生活平台帐号的唯一标识-
openidstring用户在当前小程序的唯一标识-
cityCodeString用户选择城市编码 
locationCityCodestring用户当前定位城市编码-
registerCityCodestring用户归属城市编码,即用户注册地-
phonestring用户手机号-

注意:

2.5 authorize

用途说明

提前向用户发起授权请求。

请求参数

属性类型默认值必填说明最低版本
scopestring-需要获取权限的 scope-
successfunction-接口调用成功的回调函数(授权成功)-
failfunction-接口调用失败的回调函数(授权失败)-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

scope说明:

scope对应接口说明最低版本
scope.userInfogetUserInfo、login用户信息-
scope.camerascanCode摄像头-

2.6 requestPayment

用途说明

调用建行生活收银台。

请求参数

属性类型默认值必填说明最低版本
payInfostring-支付参数-

payInfo参数内容:

属性类型可为空必填说明最低版本
MERCHANTIDchar(15)YF商户代码;由建行统一分配-
POSIDchar(9)YF柜台代码;由建行统一分配-
BRANCHIDchar(9)YF分行代码;由建行统一分配-
POSID19char(19)NF商户19位终端号;由建行统一分配,使用微信支付时上送。仅作为参数传递,不参与MAC校验-
PLATMCTIDchar(19)YF外部平台商户号;当使用外部商户号时,建行商户号、柜台号、分行号及终端号无需上送。当该字段有值时参与MAC校验,否则不参与MAC校验-
ORDERIDchar(30)YT订单号;由商户提供,最长30位-
PAYMENTnumber(16,2)YT付款金额;由商户提供,最长30位-
CURCODEchar(2)YT币种;缺省为01-人民币(只支持人民币支付)-
TXCODEchar(6)YT交易码;由建行统一分配为520100-
REMARK1char(30)NT备注1;网银不处理,直接传到城综网,该字段只支持送数字和英文-
REMARK2char(30)NT备注2;上送YS开头的服务方编号,与PLATFORMID保持一致-
TYPEchar(1)YT接口类型;1- 防钓鱼接口-
GATEWAYchar(100)YT网关类型;默认送0-
CLIENTIPchar(40)NT客户端IP;客户在商户系统中的IP-
REGINFOchar(256)NT客户注册信息;客户在商户系统中注册的信息,中文需使用escape编码-
PROINFOchar(256)NT商品信息;客户购买的商品,中文需使用escape编码-
REFERERchar(100)NT商户URL;商户送空值即可-
INSTALLNUMchar(2)NF分期期数;信用卡支付分期期数,一般为 3、6、12 等,必须为大于 1 的整数。 仅当分期支付时上送该字段,无此字段上送时,则视为普通支付。-
THIRDAPPINFOchar(40)YT客户端标识;通过建行生活APP下单场景,订单中客户端标识固定设为comccbpay1234567890cloudmerchant-
TIMEOUTchar(14)NF订单超时时间;格式:YYYYMMDDHHMMSS(如:20120214143005)
银行系统时间> TIMEOUT时拒绝交易,若送空值则不判断超时。
当该字段有值时参与MAC校验,否则不参与MAC校验。
-
USERIDchar(100)NF在中国建设银行App环境需提供。 当该字段有值时参与MAC校验,否则不参与MAC校验-
TOKENchar(100)NF在中国建设银行App环境需提供。 当该字段有值时参与MAC校验,否则不参与MAC校验-
PAYSUCCESSURLchar(100)NF在中国建设银行App环境考虑,如需指定支付成功页面需提供,需对URL编码,生产环境必须为HTTPS。未提供则默认跳转到建行生活的支付成功页面 当该字段有值时参与MAC校验,否则不参与MAC校验-
PAYBITMAPchar(10)NF支付位图;默认为空,只需要展示龙支付时请送0100000000
当该字段有值时参与MAC校验,否则不参与MAC校验。
-
POINTAVYIDvarchar(6)NF积分二级活动编号;默认为空,特定场景使用。龙支付积分二级活动上送 010051-
DCEPDEPACCNOvarchar(32)NF数字人民币收款钱包编号;默认为空,特定场景使用。数字人民币商户绑定的收款钱包编号-
COUPONAVYIDvarchar(32)NF有价券活动编号;默认为空,特定场景使用。-
ONLY_CREDIT_PAY_FLAGvarchar(1)NF限制信用卡支付标志;默认为空,特定场景使用。当有价券活动编号不为空时生效,送Y限制仅信用卡能支付,送N或空不作限制-
FIXEDPOINTVALvarchar(16)NF固定抵扣积分值;默认为空,特定场景使用。上送该值时,若用户不满足积分使用条件将拒绝支付-
EXTENDPARAMSvarchar(256)NF积分二级活动编号;默认为空,特定场景使用。上送约定JSON格式字符串-
PLATFORMPUBvarchar(256)YF服务方公钥;仅作为源串参加MD5摘要,不作为参数传递-
MACchar(32)TTMD5加密串;采用标准MD5算法,对以上字段进行MAC加密(32位小写),由商户实现。-
PLATFORMIDchar(16)YT服务方编号;仅作为参数传递,不参与MAC校验-
ENCPUBvarchar(512)YF商户公钥密文;使用服务方公钥对商户公钥后30位进行RSA加密并base64后的密文。
若商户已经上架建行生活并同步公钥,可以不再上送商户公钥。仅作为参数传递,不参与MAC校验
-
SCNIDchar(32)NF场景编号;默认为空,埋点使用。特色场景的唯一标识。仅作为参数传递,不参与MAC校验-
SCN_PLTFRM_IDchar(32)NF场景平台编号;默认为空,埋点使用。场景平台唯一标识。仅作为参数传递,不参与MAC校验 

注意:

2.7 ccblife_requestPayment

用途说明

调用建行生活收银台。

请求参数

属性类型默认值必填说明最低版本
miniIdstring-本小程序id-
successPagestring-成功页面的路径,不设置则跳转建行生活APP的支付成功页面-
payInfoobject-支付参数-

payInfo参数内容

属性类型可为空必填说明最低版本
MERCHANTIDchar(15)商户代码;由建行统一分配-
POSIDchar(9)柜台代码;由建行统一分配-
BRANCHIDchar(9)分行代码;由建行统一分配-
POSID19char(19)商户19位终端号;由建行统一分配,仅作为参数传递,不参与MAC校验-
ORDERIDchar(30)订单号;由商户提供,最长30位-
PAYMENTnumber(16,2)付款金额;由商户提供,最长30位-
CURCODEchar(2)币种;缺省为01-人民币(只支持人民币支付)-
TXCODEchar(6)交易码;由建行统一分配为520100-
REMARK1char(30)备注1;网银不处理,直接传到城综网,该字段只支持送数字和英文-
REMARK2char(30)备注2;上送YS开头的服务方编号-
TYPEchar(1)接口类型;1- 防钓鱼接口-
GATEWAYchar(100)网关类型;默认送0-
CLIENTIPchar(40)客户端IP;客户在商户系统中的IP-
REGINFOchar(256)客户注册信息;客户在商户系统中注册的信息,中文需使用escape编码-
PROINFOchar(256)商品信息;客户购买的商品,中文需使用escape编码-
REFERERchar(100)商户URL;商户送空值即可-
THIRDAPPINFOchar(40)客户端标识;通过建行生活APP下单场景,订单中客户端标识固定设为comccbpay1234567890cloudmerchant-
TIMEOUTchar(14)订单超时时间;格式:YYYYMMDDHHMMSS(如:20120214143005)
银行系统时间> TIMEOUT时拒绝交易,若送空值则不判断超时。
当该字段有值时参与MAC校验,否则不参与MAC校验。
-
PAYBITMAPchar(10)支付位图;默认为空,只需要展示龙支付时请送0100000000
当该字段有值时参与MAC校验,否则不参与MAC校验。
-
PLATFORMPUBvarchar(256)服务方公钥;仅作为源串参加MD5摘要,不作为参数传递-
MACchar(32)MD5加密串;采用标准MD5算法,对以上字段进行MAC加密(32位小写),由商户实现。-
PLATFORMIDchar(16)服务方编号;仅作为参数传递,不参与MAC校验-
ENCPUBvarchar(512)商户公钥密文;使用服务方公钥对商户公钥后30位进行RSA加密并base64后的密文。
若商户已经上架建行生活并同步公钥,可以不再上送商户公钥。仅作为参数传递,不参与MAC校验
-

注意:

2.8 navigateTo

用途说明

跳转建行生活页面 | 外部H5页|建信小程序 | 微信小程序。

请求参数

属性类型默认值必填说明最低版本
typenumber-跳转页面类型-
toPagestring-跳转路径,类型为小程序本值为空时调起首页。-
isNewViewbooleanfalse是否打开新WebView,当type为1或2时有效。值为false时用进入小程序前入口所在页面的webview打开,若不存在则用新webview打开。-
isShowHeaderbooleanfalse是否展示通用标题栏,当type为1或2时有效-
headerNamestring-标题栏名称,isShowHeader为true时有效-
headerRightTypenumber0展示标题栏时右边按钮的类型-
paramstring-跳转携带的参数,type非0时拼接到最终URL后-
miniIdstring-跳转小程序id,type为3或4时有效-
miniVersionnumber0微信小程序版本,type为4时有效 
successfunction-接口调用的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

type 的合法值:

说明最低版本
0建行生活原生页面-
1建行生活H5页面-
2外部H5页面-
3Jump小程序-
4微信小程序-

headerRightType 的合法值:

说明最低版本
0关闭按钮-
1分享按钮-

miniVersion 的合法值:

说明最低版本
0发布版-
1预览版-
2测试版-

响应内容

state 的合法值:

说明最低版本
0跳转成功-
1跳转失败-

2.9 scanCode

用途说明

建行生活App的扫码功能,扫描建行生活提供的业务二维码(扫码支付等)需要用本接口而非jump.scanCode

请求参数

属性类型默认值必填说明最低版本
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

响应内容

属性类型说明最低版本
contentstring扫码结果-

state 的合法值:

说明最低版本
0扫码成功-
1非有效业务二维码,无法解析-

2.10 openPayCode

用途说明

打开支付码。

请求参数

属性类型默认值必填说明最低版本
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

响应内容

state 的合法值:

说明最低版本
0打开成功-
1打开失败-

2.11 callMap

用途说明

调起手机内的地图App。支持苹果地图|高德地图|百度地图。

请求参数

属性类型默认值必填说明最低版本
paramsobject-参数-
needNavigationbooleanfalse是否需要导航-
addressstring-商户地址-
lgtnumber-商户纬度-
lttnumber-商户经度-
cityNamestring-城市名称-
business_namestring-商户名称-
self_lgtnumber-客户维度-
self_lttnumber-客户经度-
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

注意:

响应内容

state 的合法值:

说明最低版本
0调起地图成功-
1调起地图失败-

2.12 startFaceScan

用途说明

刷脸认证|人脸校验

请求参数

属性类型默认值必填说明最低版本
PLATFORM_IDstring-服务方ID-
namestring--姓名-
cardTypestring-卡片类型(身份证)-
cardNumstring-身份证号码-
phoneNumstring-手机号-
showErrorstring-报错弹窗:1-显示 0-不显示-
scanOnlystring-仅刷脸:1-只刷脸,不发校验刷脸流水的交易-
Stm_Chnl_IDstring-渠道号,默认为建行生活渠道-
Stm_Chnl_Txn_CDstring-渠道交易码,默认为建行生活渠道交易码-
txCodestring-安全交易码,默认为建行生活安全交易码-
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

响应内容

属性类型说明最低版本
successstring刷脸认证是否成功:0-失败,1-成功-
Comm_Auth_FieldsstringUUID-
Apl_Aply_TrcNostring全局流水号-

2.13 userStatus

用途说明

获取用户状态信息

请求参数

属性类型默认值必填说明最低版本
PLATFORM_IDstring--服务方ID-
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

响应内容

属性类型说明最低版本
userTypestring用户类型:00游客/未登录 01钱包用户 02已注册未开钱包-
isLoginstring登录状态:0:未登录 1:已登录-

2.14 share

用途说明

分享。

请求参数

属性类型默认值必填说明最低版本
share_idstring-分享id,存在分享ID时先调接口获取分享内容-
textstring--分享的描述-
titlestring--标题-
urlstring--链接-
imagestring--图片链接-
typestring--0--分享链接,1--分享微信朋友,2--分享朋友圈-
base64Picstring--图片base64格式化-
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

响应内容

属性类型说明最低版本
typestring0: 取消分享 1:分享到微信 2:分享到朋友圈-

2.15 checkUser

用途说明

校验用户身份。

请求参数

属性类型默认值必填说明最低版本
platformIdstring-服务方编号,非空-
sceneIdstring--场景ID-
checkTypestring--校验类型 1-校验平台支付密码 2-校验平台登录密码-
checkScopestring--验密有效范围,0-App内有效(默认值) 1-同类场景有效 2-场景内有效 3-场景内同功能有效 4-一次性有效-
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

响应内容

属性类型说明最低版本
tokenstring唯一验密流水号,每次重新生成-
codestring校验结果状态码
0:校验完成
1:已在其他功能场景校验通过,且在有效期内
-1:用户取消校验
-2:校验失败,当前场景未配置校验类型、用户状态异常等原因
-

注意:

2.15 RealNameAuthorization

用途说明

实名认证。

请求参数

属性类型默认值必填说明最低版本
platformIdstring-服务方编号,非空-
successfunction-接口调用成功的回调函数-
failfunction-接口调用失败的回调函数-
completefunction-接口调用结束的回调函数(调用成功、失败都会执行)-

响应内容

属性类型说明最低版本
successstring实名结果 0-失败,1-成功-