接口描述
通过账户主体类型与标识查询用户名下获得票券的详细信息，单次可查询十条票券活动记录，返回结果做数据权限控制。(只用于展示，不可作为资金清算依据)
请求方式
POST
生产调用地址
https://openapi.unionpay.com/upapi/mkt/kol/userCoupon/v1
测试调用地址
https://openapi.unionpay.com/upapi/mkt/kol/userCoupon/v1
HTTP报文体参数
| 中文名称 | 英文名称 | 域类型 | 域长度 | 默认值 | 请求要求 | 备注 | |
|---|---|---|---|---|---|---|---|
| 渠道方代码 | chnlId | string | an4 | M-必填 | 渠道ID。由银联分配，申请银联营销能力开放产品后自动分配，与开放平台报文头APPID一一对应
|
||
| 流水号 | transSeq | string | an..64 | M-必填 | 流水号
|
||
| 优惠券主体类型 | acctEntityTp | string | an2 | M-必填 | 账户主体类型可选：用户、卡号、手机号（N选一）UP01-手机号；UP02-卡号；UP03-银联统一用户ID；UP05-外部用户IDUP06-网络支付平台用户ID；UP07-证件号。
|
||
| 优惠券主体标识-手机号 | mobile | string | an..64 | C-按条件必填 | 当entityTp为01时，mobile必填；当entityTp为03时，cardNo、mobile、openId三选一必填；
该参数已配置加密规则：SM4
该参数已配置加密规则：SM4 查看详情 |
||
| 优惠券主体标识-卡号 | cardNo | string | an..64 | C-按条件必填 | 当entityTp为02时，cardNo必填；当entityTp为03时，cardNo、mobile、openId三选一必填；
该参数已配置加密规则：SM4
该参数已配置加密规则：SM4 查看详情 |
||
| 优惠券主体标识-云闪付注册用户 | openId | string | an..256 | C-按条件必填 | 当entityTp为03时，cardNo、mobile、openId三选一必填；当entityTp为01、02时，openId可不填；
|
||
| 优惠券主体标识-外部用户 | extUserId | string | n..64 | C-按条件必填 | 当entityTp为05时，extUserId必填，取值为外部调用方定义的用户标识
|
||
| 外部AppId | extAppId | string | n..64 | C-按条件必填 | 当entityTp为05时，extAppId必填，取值为银联为调用方分配的二维码系统APPID
|
||
| 优惠券主体标识-网络支付平台用户 | huserId | string | an..128 | C-按条件必填 | 当entityTp为06时，huserId必填，取值为网络支付平台用户标识
|
||
| 优惠券主体标识-证件号 | sm3CertId | string | C-按条件必填 | acctEntityTp为UP07则必填，采用国密SM3加密转16进制小写
|
|||
| 活动ID列表 | activityIdList | list | M-必填 | 最大值：10，如果列表中任一活动ID不在机构的数据权限内，则认为非法请求，用英文;加以分割
|
|||
| 优惠券状态 | acctSt | string | an1 | C-按条件必填 | 0 所有；1 正常；2 已注销（预留，暂不使用）；3 已冻结；4 已归并（预留，暂不使用）；5 已过期；6 已使用
|
||
| 当前页 | currentPage | string | a2 | M-必填 | 券码列表的页码，起始页为第0页
|
||
| 页大小 | pageSize | string | a2 | M-必填 | 券码列表分页大小(最大值：20）
|
HTTP消息头参数
| 中文名称 | 英文名称 | 域类型 | 域长度 | 默认值 | 样例值 | 请求要求 | 备注 | |
|---|---|---|---|---|---|---|---|---|
| 版本号 | version | string | 8 | 取值：1.0.0 | M-必填 |
|
||
| 发送方索引类型 | appType | string | 2 | M-必填 | 取值： 00：银联索引 ；01 机构索引 ；02 商户索引
|
|||
| 发送方索引标识码 | appId | string | 32 | M-必填 | appId由开放平台网关分配，取值开放平台网关API认证账号
|
|||
| 接口类型 | bizMethod | string | 64 | mkt.kol.userCoupon.v1 | M-必填 |
|
||
| 签名 | sign | string | 344 | M-必填 | 对报文摘要的签名
|
|||
| 签名类型 | signMethod | string | 20 | M-必填 | 取值：RSA2：先使用SHA-256计算摘要，再使用RSA完成签名，样例代码参考3.3；SM2：先使用SM3计算摘要，再使用SM2完成签名，样例代码参考3.4
|
|||
| 发送方流水号 | reqId | string | 64 | M-必填 | 由发送方自动生成
|
|||
| 时间戳 | reqTs | string | 32 | M-必填 | 当前时间戳
|
同步应答参数
| 中文名称 | 英文名称 | 域类型 | 域长度 | 默认值 | 请求要求 | 备注 | |
|---|---|---|---|---|---|---|---|
| 应答码 | code | string | an10 | M-必填 | 成功应答码为’0000000000’
失败应答码格式：
第1-2位表示应答码生成方；
第3-10位表示错误原因；
取值详见应答码信息。
|
||
| 应答文案 | msg | string | ans..128 | O-选填 | 同一个应答码可对应多个不同的描述，对处理结果进行详细提示
|
||
| 应答码 | subCode | string | ans..10 | C-按条件必填 | 二级应答，当code非成功应答时才出现，并且描述了详细的业务处理失败的原因。
|
||
| 应答文案 | subMsg | string | ans..128 | C-按条件必填 | 同一个详细错误码可对应多个不同的描述，对处理结果进行详细提示。 包含多个错误信息，供进一步分析错误原因使用。
|
||
| 业务应答 | params | string | O-选填 |
|
示例代码
请求报文头参数
{
“version”:”1.0.0”,
“appType”:”01”,
“appId”:”up_5issuytt11s_adqov”,
“bizMethod”:”mkt.kol.userCoupon.v1”,
“sign”:”2MsthJAk1HKoop2xjCpLhNUDMeXOAiHyful4WonY+v8yoc8oQHiS1cKnqUHdoLlIZESb3kXXFJHHtHU6mknrI+JTWsAlmkEPCsSlJ6Uw3G”,
“signMethod”:”RSA2”,
“reqId”:”hfsjau2jirnwqn128h3j1nbsa213”,
“reqTs”:”1629365633609”
}
请求报文参数
{
"chnlId":"1046",
"transSeq":"20210526164720695053008152703826",
"acctEntityTp":"UP01",
"cardNo":"",
"mobile":"13618946784",
"userId":"",
"activityIdList":["310001233","310001234","310001235"],
"currentPage":"2",
"pageSize":"10"
}
中国银联版权所有© 沪ICP备07032180号-2 沪公网安备31011502002335号
