接口描述
外部机构向指定用户赠送优惠券，需指定优惠券入账的用户维度与入账参数。
请求方式
POST
生产调用地址
https://openapi.unionpay.com/upapi/mkt/cpn/couponAcquire/v1
测试调用地址
https://openapi.unionpay.com/upapi/mkt/cpn/couponAcquire/v1
HTTP报文体参数
| 中文名称 | 英文名称 | 域类型 | 域长度 | 默认值 | 请求要求 | 备注 | |
|---|---|---|---|---|---|---|---|
| 渠道方代码 | chnlId | string | an4 | M-必填 |
|
||
| CMD | cmd | string | a13 | M-必填 | 固定值：couponAcquire
|
||
| 接入方 | accessId | string | an2 | M-必填 | 固定填写“UP”
|
||
| Qid | qid | string | an..64 | M-必填 | 外部接入方定义的主键，保证唯一，即流水号，用于幂等校验
|
||
| 外部活动ID | outerActivityNo | string | an..64 | C-按条件必填 | 仅当发放外部券码时，上送；发放银联优惠券时，该字段不填。
|
||
| 请求日期 | orderDt | string | an8 | M-必填 | 格式为yyyyMMdd，需为当日
|
||
| 请求跟踪号 | traceId | string | an..64 | M-必填 | 银联营销平台用于上下文串联，取值可与QID相同，不强制校验是否唯一
|
||
| 优惠券ID | discountId | string | an..64 | M-必填 | 票券活动ID，由银联营销平台生成，31打头的16位数字 ，同优惠券状态通知接口的couponId。
|
||
| 下载数量 | discountNum | string | n12 | M-必填 | 一笔请求中的发券的数量，建议一次只发一张。
|
||
| 优惠券主体类型 | entityTp | string | an2 | M-必填 | 01：手机号维度；02：卡号维度；03：云闪付注册用户ID维度；05：外部用户ID维度；06：网络支付平台用户。07：证件号用户维度。票券的账户维度，同一个优惠券ID下的优惠券，其发放维度与核销维度一致，银行需确保支付交易中上送对应的要素。
|
||
| 优惠券主体标识_卡号 | cardNo | string | an..64 | C-按条件必填 | 当entityTp为03时，cardNo、mobile、openId三选一必填；当entityTp为02时，cardNo必填
该参数已配置加密规则：SM4 查看详情 |
||
| 优惠券主体标识_手机号 | mobile | string | an..64 | C-按条件必填 | 当entityTp为03时，cardNo、mobile、openId三选一必填；当entityTp为01时，mobile必填
该参数已配置加密规则：SM4 查看详情 |
||
| 优惠券主体标识_外部用户 | extUserId | string | an..256 | C-按条件必填 | 当entityTp为05时，extUserId必填，取值为外部调用方定义的用户标识
|
||
| 优惠券主体标识-云闪付注册用户 | openId | string | an..256 | C-按条件必填 | 当entityTp为03时，cardNo、mobile、openId三选一必填；当entityTp为01、02时，openId可不填；
|
||
| 外部AppId | extAppId | string | n..64 | C-按条件必填 | 当entityTp为05时，extAppId必填，取值为银联为调用方分配的二维码系统APPID
|
||
| 优惠券主体标识-网络支付平台用户 | huserId | string | an..128 | C-按条件必填 | 当entityTp为06时，huserId必填，取值为网络支付平台用户标识
|
||
| 券码 | couponCd | string | an..256 | C-按条件必填 | 仅当发放外部券码时，自主上送券码；发放银联优惠券时，券码由银联生成并返回
|
||
| 是否实名 | isRealNm | string | a1 | C-按条件必填 | 当票券配置限制是否实名用户时上送，一般默认为空。0-未实名；1-实名。
|
||
| 城市ID | cityId | string | an..10 | C-按条件必填 | 当票券配置限制领取城市时上送，对应行政区划代码
|
||
| 证件号 | certId | string | an..128 | C-按条件必填 | entityTp为07则必填。 SM3，16进制编码，小写
|
||
| logId | logId | string | an..128 | C-按条件必填 | 不强制校验是否唯一
|
HTTP消息头参数
| 中文名称 | 英文名称 | 域类型 | 域长度 | 默认值 | 样例值 | 请求要求 | 备注 | |
|---|---|---|---|---|---|---|---|---|
| 版本号 | version | string | 8 | M-必填 | 取值：1.0.0
|
|||
| 发送方索引类型 | appType | string | 2 | M-必填 | 取值： 00：银联索引 01 机构索引 02 商户索引
|
|||
| 发送方索引标识码 | appId | string | 32 | M-必填 | appId由开放平台网关分配，取值开放平台网关API认证账号
|
|||
| 接口类型 | bizMethod | string | 64 | M-必填 | 取值：mkt.cpn.couponAcquire.v1
|
|||
| 签名 | sign | string | 344 | M-必填 | 对报文摘要的签名
|
|||
| 签名方式 | signMethod | string | 20 | M-必填 | 取值：RSA2、SM2，根据实际签名算法填写
|
|||
| 发送方流水号 | reqId | string | 64 | M-必填 | 由发送方自动生成
|
|||
| 时间戳 | reqTs | string | 32 | M-必填 | 当前时间戳
|
同步应答参数
| 中文名称 | 英文名称 | 域类型 | 域长度 | 默认值 | 请求要求 | 备注 | |
|---|---|---|---|---|---|---|---|
| 应答码 | code | string | an10 | M-必填 | 成功应答码为’0000000000’失败应答码格式：第1-2位表示应答码生成方；第3-10位表示错误原因；取值详见应答码信息。
|
||
| 应答码描述 | msg | string | ans..128 | M-必填 | 同一个应答码可对应多个不同的描述，对处理结果进行详细提示
|
||
| 详细应答码 | subCode | string | an10 | C-按条件必填 | 当应答码非成功时出现，并且描述了详细的业务处理失败的原因。
|
||
| 详细应答码描述 | subMsg | string | ans..128 | C-按条件必填 | 同一个详细错误码可对应多个不同的描述，对处理结果进行详细提示。包含多个错误信息，供进一步分析错误原因使用。
|
||
| 优惠券ID | discountId | string | an..64 | M-必填 | 票券活动ID，由银联营销平台生成，31打头的16位数字；同优惠券状态通知接口的couponId。
|
||
| Qid | qid | string | an..64 | M-必填 | 外部接入方定义的主键，保证唯一，即流水号，用于幂等校验
|
||
| 券码ID | couponCd | string | an..256 | C-按条件必填 | 当应答码为成功时，券码必填。每一笔赠送请求对应一个唯一的券码，如果一次发放两张，也是同一个券码。
|
||
| 券生效时间 | couponBeginTs | string | an14 | M-必填 | 本次下载的优惠券有效期起始时间。注：格式为yyyyMMddHHmmss，在operaSt为00情况下必返回
|
||
| 券失效时间 | couponEndTs | string | an14 | M-必填 | 本次下载的优惠券有效期结束时间。注：格式为yyyyMMddHHmmss，在operaSt为00情况下必返回
|
示例代码
//请求报文头参数
{
“version”:”1.0.0”,
“appType”:”01”,
“appId”:”up_5issuytt11s_adqov”,
“bizMethod”:”mkt.cpn.couponAcquire.v1 ”,
“sign”:”2MsthJAk1HKoop2xjCpLhNUDMeXOAiHyful4WonY+v8yoc8oQHiS1cKnqUHdoLlIZESb3kXXFJHHtHU6mknrI+JTWsAlmkEPCsSlJ6Uw3G”,
“signMethod”:”RSA2”,
“reqId”:”hfsjau2jirnwqn128h3j1nbsa213”,
“reqTs”:”1629365633609”
}
//请求报文参数
{
"chnlId": "00010000",
"accessId": "UP",
"cmd": "couponAcquire",
"qid": "2019122712341234",
"outerActivityNo": "10000789",
"orderDt": "20191227",
"traceId": "trace2019122712341234",
"discountId": "3112019122000939",
"discountNum": "2",
"entityTp": " 01",
"mobile": "13022982789",
"couponCd": "111111",
" isRealNm ": "1",
" cityId ": "122",
" certId ": "320257202006120154",
"logId": "log2019122712341234"
}
中国银联版权所有© 沪ICP备07032180号-2 沪公网安备31011502002335号
