银联权益信息

增值 收单机构 商户 开发者 发卡机构 快速接入
查询、核销银联权益信息,并结合实际使用场景核销用户权益

接入服务商:银联开放平台

API ID:54

接口状态:正常

业务申请
沙箱测试
沙箱调用

接口名称

获取token

接口描述

产品token是开放平台每个产品的全局唯一接口调用凭据,用户调用各接口时都需使用产品token。

接口地址

测试地址: https://openapi.unionpay.com/upapi/uprstest/token


生产地址: https://openapi.unionpay.com/upapi/uprs/token

请求方式

HTTP GET

请求url参数

名称 标识 字段类型 长度 请求要求 默认值 备注
用户唯一凭证 app_id string M-必填 详情可在登录开放平台后“个人中心-我的信息-API认证信息-API认证账号”中查看。
用户唯一凭证密钥 app_secret string M-必填 详情可在登录开放平台后“个人中心-我的信息-API认证信息-API认证密钥”中查看。

应答参数

名称 标识 字段类型 长度 请求要求 默认值 备注
产品token token string M-必填 获取到的凭证。
过期时间 expire_in string M-必填 凭证有效时间,单位:秒。

接口名称

查询权益信息

接口描述

根据权益归属地区、权益类别,返回权益列表,列表项包含权益和其规则详情。

接口地址

测试地址: https://openapi.unionpay.com/upapi/uprstest/getRightInfoByOrganizer


生产地址: https://openapi.unionpay.com/upapi/uprs/getRightInfoByOrganizer

请求方式

HTTP POST

请求url参数

名称 标识 字段类型 长度 请求要求 默认值 备注
产品token token string M-必填 详情请参考“获取token”接口中应答参数“token”的具体数据。
签名信息 sign string M-必填 详细签名算法可参考“接入指南”板块第3条。
时间戳 ts long M-必填 单位:毫秒。

请求报文体参数

名称 标识 字段类型 长度 请求要求 默认值 备注
地区 organizer int M-必填 具体取值请参考帮助与文档
权益类别 bussType string M-必填 具体取值请参考帮助与文档
预留字段 reserve string O-选填
用户身份 appId string M-必填 请登录银联技术开放平台申请APP_ID

应答参数

名称 标识 字段类型 长度 请求要求 默认值 备注
应答码 respCd string M-必填
应答消息 respMsg string M-必填 返回消息详情。
应答报文 data map M-必填
权益列表 rightList array M-必填
权益ID rightId int M-必填
权益名称 name string 64 M-必填
权益描述 desc string 128 M-必填
权益规则列表 ruleList array O-选填
权益规则ID ruleId int M-必填
权益规则名称 name string M-必填
权益规则附加信息 additionInfo string O-选填
开始时间 startTs string 8 M-必填 YYYYMMdd
到期时间 endTs string 8 M-必填 YYYYMMdd
支持卡等级 cardRankSup string 4 M-必填 4位位图字符串,分别表示是否支持普卡、金卡、白金、钻石,0表示支持,1表示不支持。例如仅支持白金卡为”0010”
支持卡性质 cardAttrSup string 4 M-必填 4位位图字符串,分别表示是否支持借记卡、贷记卡、准贷记卡、其他卡,0表示支持,1表示不支持。例如仅支持信用卡为”0110”(信用卡包括贷记卡和准贷记卡)
支持黑白卡BIN限制 cardBinSup string 2 M-必填 00表示不支持,01表示支持
支持卡号黑白名单 cardLimitSup string 2 M-必填 00表示不支持,01表示支持

接口名称

卡号查询权益

接口描述

根据银行卡卡号、权益类别、归属地等信息查询的权益余量。

接口地址

测试地址: https://openapi.unionpay.com/upapi/uprstest/getSurplusByCard


生产地址: https://openapi.unionpay.com/upapi/uprs/getSurplusByCard

请求方式

HTTP POST

请求url参数

名称 标识 字段类型 长度 请求要求 默认值 备注
产品token token string M-必填 详情请参考“获取token”接口中应答参数“token”的具体数据。
签名信息 sign string M-必填 详细签名算法可参考“接入指南”板块第3条。
时间戳 ts long M-必填 单位:毫秒。

请求报文体参数

名称 标识 字段类型 长度 请求要求 默认值 备注
银行卡卡号 cardNo string M-必填 16-19位数字
归属地 organizer int O-选填 具体取值请参考帮助与文档
权益类别 bussType string 2 M-必填 具体取值请参考帮助与文档
预留参数 reserve string 64 O-选填 预留字段
用户身份 appId string M-必填 请登录银联技术开放平台申请APP_ID

应答参数

名称 标识 字段类型 长度 请求要求 默认值 备注
应答码 respCd string M-必填
应答消息 respMsg string M-必填 返回消息详情。
应答报文 data map M-必填
余量列表 surplusList array M-必填
权益规则ID ruleId int M-必填
权益名称 name string 64 M-必填
权益余量 surplus int M-必填
开始时间 startTs string 8 M-必填 YYYYMMdd
到期时间 endTs string 8 M-必填 YYYYMMdd

接口名称

卡号查询权益(合)

接口描述

本接口只对有业务合作的合作方开放,根据银行卡卡号、权益类别、归属地等信息查询合作方有关的权益余量。

接口地址

测试地址: https://openapi.unionpay.com/upapi/uprstest/getSurplusByCardForPartner


生产地址: https://openapi.unionpay.com/upapi/uprs/getSurplusByCardForPartner

请求方式

HTTP POST

请求url参数

名称 标识 字段类型 长度 请求要求 默认值 备注
产品token token string M-必填 详情请参考“获取token”接口中应答参数“token”的具体数据。
签名信息 sign string M-必填 详细签名算法可参考“接入指南”板块第3条。
时间戳 ts long M-必填 单位:毫秒。

请求报文体参数

名称 标识 字段类型 长度 请求要求 默认值 备注
银行卡卡号 cardNo string M-必填 16-19位数字
接入合作方 partner int M-必填 接入权益平台的合作方ID
归属地 organizer int O-选填 具体取值请参考帮助与文档
权益类别 bussType string 2 M-必填 具体取值请参考帮助与文档
预留参数 reserve string 64 O-选填 预留字段
用户身份 appId string M-必填 请登录银联技术开放平台申请APP_ID

应答参数

名称 标识 字段类型 长度 请求要求 默认值 备注
应答码 respCd string M-必填
应答消息 respMsg string M-必填 返回消息详情。
应答报文 data map M-必填
余量列表 surplusList array M-必填
权益名称 name string 64 M-必填
权益规则ID ruleId int M-必填
权益余量 surplus int M-必填
开始时间 startTs string M-必填 YYYYMMdd
到期时间 endTs string M-必填 YYYYMMdd
合作定义值 customValue string O-选填

接口名称

定义值查询权益

接口描述

本接口只为有业务合作的合作方开放,根据地区、合作方、合作自定义值等查询权益,返回权益余量列表。

接口地址

测试地址: https://openapi.unionpay.com/upapi/uprstest/getSurplusByCustomKey


生产地址: https://openapi.unionpay.com/upapi/uprs/getSurplusByCustomKey

请求方式

HTTP POST

请求url参数

名称 标识 字段类型 长度 请求要求 默认值 备注
产品token token string M-必填 详情请参考“获取token”接口中应答参数“token”的具体数据。
签名信息 sign string M-必填 详细签名算法可参考“接入指南”板块第3条。
时间戳 ts long M-必填 单位:毫秒。

请求报文体参数

名称 标识 字段类型 长度 请求要求 默认值 备注
银行卡卡号 cardNo string O-选填 16-19位数字
合作方 partner int M-必填 接入的合作方ID
归属地 organizer int O-选填 具体取值请参考帮助与文档
权益类别 bussType string 2 M-必填 具体取值请参考帮助与文档
合作定义值 customKey string O-选填 根据接入合作方需求定义
预留参数 reserve string 64 O-选填 预留字段
用户身份 appId string M-必填 请登录银联技术开放平台申请APP_ID

应答参数

名称 标识 字段类型 长度 请求要求 默认值 备注
应答码 respCd string M-必填
应答消息 respMsg string M-必填 返回消息详情。
应答报文 data map M-必填
余量列表 surplusList array M-必填
权益卡号 cardNo string O-选填 权益所属银行卡号,默认不返回,如合作方需要返回卡号需申请
权益规则ID ruleId int M-必填
权益名称 name string 64 M-必填
权益余量 surplus int M-必填
开始时间 startTs string 8 M-必填 YYYYMMdd
到期时间 endTs string 8 M-必填 YYYYMMdd
权益自定义值 customValue string O-选填 此处合作定义值与传递的合作定义值可能不同,以具体合作业务为准

接口名称

卡号核销权益

接口描述

本接口只对有业务合作的合作方开放,根据卡号、合作方、归属地、权益类别及合作定义值完成权益核销操作。

接口地址

测试地址: https://openapi.unionpay.com/upapi/uprstest/verifyRightsByCardAndCustomKey


生产地址: https://openapi.unionpay.com/upapi/uprs/verifyRightsByCardAndCustomKey

请求方式

HTTP POST

请求url参数

名称 标识 字段类型 长度 请求要求 默认值 备注
产品token token string M-必填 详情请参考“获取token”接口中应答参数“token”的具体数据。
签名信息 sign string M-必填 详细签名算法可参考“接入指南”板块第3条。
时间戳 ts long M-必填 单位:毫秒。

请求报文体参数

名称 标识 字段类型 长度 请求要求 默认值 备注
银行卡卡号 cardNo string M-必填 16-19位数字
合作方 partner int M-必填 接入的合作方ID
归属地 organizer int O-选填 具体取值请参考帮助与文档
权益类别 bussType string 2 M-必填 具体取值请参考帮助与文档
合作定义值 customKey string O-选填 根据接入合作方需求定义
核销次数 surplus int M-必填 核销次数
是否生成订单 genOrder string M-必填 该权益是否生成订单 00 不生成 01 生成
预留参数 reserve string 64 O-选填 预留字段
用户身份 appId string M-必填 请登录银联技术开放平台申请APP_ID

应答参数

名称 标识 字段类型 长度 请求要求 默认值 备注
应答码 respCd string M-必填
应答消息 respMsg string M-必填 返回消息详情。

接口名称

手机号核销权益

接口描述

本接口只对有业务合作的合作方开放,根据手机号、合作方、归属地、权益类别及合作定义值完成权益核销操作。

接口地址

测试地址: https://openapi.unionpay.com/upapi/uprstest/verifyRightsByPhoneAndCustomKey


生产地址: https://openapi.unionpay.com/upapi/uprs/verifyRightsByPhoneAndCustomKey

请求方式

HTTP POST

请求url参数

名称 标识 字段类型 长度 请求要求 默认值 备注
产品token token string M-必填 详情请参考“获取token”接口中应答参数“token”的具体数据。
签名信息 sign string M-必填 详细签名算法可参考“接入指南”板块第3条。
时间戳 ts long M-必填 单位:毫秒。

请求报文体参数

名称 标识 字段类型 长度 请求要求 默认值 备注
手机号 phone string 11 M-必填 11位数字,仅支持大陆地区
合作方 partner int M-必填 接入的合作方ID
归属地 organizer int O-选填 具体取值请参考帮助与文档
权益类别 bussType string 2 M-必填 具体取值请参考帮助与文档
合作定义值 customKey string O-选填 根据接入合作方需求定义
核销次数 surplus int M-必填 核销次数
是否生成订单 genOrder string M-必填 该权益是否生成订单 00 不生成 01 生成
预留参数 reserve string 64 O-选填 预留字段
用户身份 appId string M-必填 请登录银联技术开放平台申请APP_ID

应答参数

名称 标识 字段类型 长度 请求要求 默认值 备注
应答码 respCd string M-必填
应答消息 respMsg string M-必填 返回消息详情。

接口名称

权益规则核销权益

接口描述

本接口只对有业务合作的合作方开放,根据卡号、权益规则ID、归属地及合作定义值完成权益核销操作。

接口地址

测试地址: https://openapi.unionpay.com/upapi/uprstest/verifyRightsByCardAndRid


生产地址: https://openapi.unionpay.com/upapi/uprs/verifyRightsByCardAndRid

请求方式

HTTP POST

请求url参数

名称 标识 字段类型 长度 请求要求 默认值 备注
产品token token string M-必填 详情请参考“获取token”接口中应答参数“token”的具体数据。
签名信息 sign string M-必填 详细签名算法可参考“接入指南”板块第3条。
时间戳 ts long M-必填 单位:毫秒。

请求报文体参数

名称 标识 字段类型 长度 请求要求 默认值 备注
卡号 cardNo string M-必填 16-19位数字
合作方 partner int M-必填 接入的合作方ID
归属地 organizer int O-选填 具体取值请参考帮助与文档
权益类别 bussType string 2 M-必填 具体取值请参考帮助与文档
权益规则ID ruleId int M-必填 权益规则ID
核销次数 surplus int M-必填 核销次数
是否生成订单 genOrder string M-必填 该权益是否生成订单 00 不生成 01 生成
预留参数 reserve string 64 O-选填 预留字段
用户身份 appId string M-必填 请登录银联技术开放平台申请APP_ID

应答参数

名称 标识 字段类型 长度 请求要求 默认值 备注
应答码 respCd string M-必填
应答消息 respMsg string M-必填 返回消息详情。

接口名称

订单状态通知

接口描述

本接口只对有业务合作的合作方开放,合作方根据自身的订单状态改变情况通知权益平台,权益平台会根据不同的订单状态进行权益核销、恢复等操作

接口地址

测试地址: https://openapi.unionpay.com/upapi/uprstest/notifyOrderState


生产地址: https://openapi.unionpay.com/upapi/uprs/notifyOrderState

请求方式

HTTP POST

请求url参数

名称 标识 字段类型 长度 请求要求 默认值 备注
产品token token string M-必填 详情请参考“获取token”接口中应答参数“token”的具体数据。
签名信息 sign string M-必填 详细签名算法可参考“接入指南”板块第3条。
时间戳 ts long M-必填 单位:毫秒。

请求报文体参数

名称 标识 字段类型 长度 请求要求 默认值 备注
权益平台订单号 orderId string 20 M-必填 权益平台订单号必填
合作方订单号 merOrderId string C-依条件必填 权益平台订单号和合作方订单号二者必填其一
合作方 partner int M-必填 接入的合作方ID
归属地 organizer int O-选填 具体取值请参考帮助与文档
订单状态 state string 2 M-必填 该订单的状态:00 支付完成 11 支付失败 12 订单取消
预留参数 reserve string 64 O-选填 预留字段
用户身份 appId string M-必填 请登录银联技术开放平台申请APP_ID

应答参数

名称 标识 字段类型 长度 请求要求 默认值 备注
应答码 respCd string M-必填
应答消息 respMsg string M-必填 返回消息详情。

接口名称

手机号查询权益

接口描述

根据银手机号、权益类别、归属地等信息查询的权益余量。

接口地址

测试地址: https://openapi.unionpay.com/upapi/uprstest/getSurplusByPhone


生产地址: https://openapi.unionpay.com/upapi/uprs/getSurplusByPhone

请求方式

HTTP POST

请求url参数

名称 标识 字段类型 长度 请求要求 默认值 备注
产品token token string M-必填 详情请参考“获取token”接口中应答参数“token”的具体数据。
签名信息 sign string M-必填 详细签名算法可参考“接入指南”板块第3条。
时间戳 ts long M-必填 单位:毫秒。

请求报文体参数

名称 标识 字段类型 长度 请求要求 默认值 备注
用户身份 appId string M-必填 请登录银联技术开放平台申请APP_ID
接入合作方 partner int M-必填 接入权益平台的合作方ID
手机号 phoneNo string M-必填 11位数字,仅支持大陆地区
归属地 organizer int O-选填 具体取值请参考帮助与文档
权益类别 bussType string 2 M-必填 具体取值请参考帮助与文档
预留参数 reserve string 64 O-选填 预留字段

应答参数

名称 标识 字段类型 长度 请求要求 默认值 备注
应答码 respCd string M-必填
应答消息 respMsg string M-必填 返回消息详情。
应答报文 data map M-必填
余量列表 surplusList array M-必填
余量ID id int M-必填
卡号 cardNo string M-必填 格式:6226*****1111
权益规则ID ruleId int M-必填
权益名称 name string 64 M-必填
权益余量 surplus int M-必填 权益可使用次数
开始时间 startTs string 8 M-必填 YYYYMMdd
到期时间 endTs string 8 M-必填 YYYYMMdd
合作定义值 customValue string O-选填
产品亮点

        为了更好面向持卡人提供权益综合服务,银联权益管理平台通过技术开放平台封装成数据接口,开放上线“银联权益信息”产品API,为开发者、权益合作商提供对外统一标准、统一流程的API调用服务。

产品详情

目前,已实现的权益类型包括洗车权益、停车权益、代驾权益、机场快速安检及贵宾厅权益(CIP)、运动权益、加油权益、话费充值权益、咨询权益(法律、医疗)、签证权益等

持卡人可通过云闪付统一APP,进行查询、核销银联权益信息,如下图:

持卡人页面展示-权益平台首页1.png

应用对象

开发者、权益合作商

接入流程
  1. 调用该API时,若只需调用“获取token”“查询权益信息”“卡号查询权益”接口,只需点击右上角“业务申请”,并认真填写相关内容,待业务接口人审核通过后即可(审核周期为2-3个工作日);

  2. 如还需其它接口,请联系业务接口人说明相关使用需求,沟通确认后,请点击右上角“业务申请”,并认真填写相关内容,待业务接口人审核通过后即可(审核周期为2-3个工作日);

  3. 技术联调,可参照《“快速接入”产品API技术文档-接入指南》

注意事项

1、非合作方用接口(接口不需要传递partner字段)可以直接通过业务申请使用;

2、合作方用接口(接口需要传递partner字段),因为合作方的权益可能涉及业务洽谈、商务谈判、技术对接、权益配置等流程,请先进行业务沟通后再进行API接入使用;

3、权益测试地址接口(tdctest.95516.com)存在网络防火墙,因此非合作方用接口可直接使用生产接口。


应答码参照:
应答码 描述
0000 处理成功
0001 服务未定义,请检查您请求的URL
8000 未知错误
8001 请求参数不完整
8002 请求参数有误
8003 权益归属地有误
8004 合作方信息有误
8005 权益类型有误
8006 卡信息有误或未读取出卡信息
8007 该合作定义值无法获取到权益
8008 未找到所需核销的权益信息或权益信息异常
8009 权益余量不足,无法核销
8010 根据合作定义值获取到的权益信息异常
8011 重复核销权益,无法核销
8012 未找到权益信息
8013 该卡未查到权益或权益已用完
8014 改权益已过期,无法核销
8015 获取权益订单信息失败
8016 获取订单附加信息失败
8017 订单状态有误
8018 订单附加信息有误,请确认附加信息是否正确(金额等参数是否传递正常)
8099 请求数据越权
9901 您的IP(XXX.XXX.XXX.XXX)没有登记,请登录银联开放平台(https://open.unionpay.com/tjweb/user/info)进行白名单登记
9902 您的IP(XXX.XXX.XXX.XXX)已被限制访问,请登录银联开放平台(open.unionpay.com)提交申诉请求
9903 您的IP(XXX.XXX.XXX.XXX)请求过于频繁,已被临时限制,请5分钟后再尝试
9904 您的 IP(XXX.XXX.XXX.XXX)不属于你设置的开发IP列表,请登录银联开放平台(open.unionpay.com)确认相关配置
9905 请求参数值有误,请确认请求参数信息
9906 您的账号不具备当前产品请求权限,如有权限,可重新获取该产品Token后再尝试
9907 app_id与app_secret验证失败
9908 您的Token已过期,请重新获取Token
9909 您的Token信息非最新Token,请确保您的系统中使用的是最新的Token值
9910 您的签名密钥未设置,请登录银联开放平台(https://open.unionpay.com/tjweb/user/info)确认相关配置
9911 您的签名信息验证不通过,请检查您的签名实现是否符合银联开放平台(open.unionpay.com)提供的签名规则
9912 您的报文格式有误,要求报文符合JSON数据格式
9913 你的报文数据有误,未通过数据信息校验,具体原因视业务需求
9914 您的报文无法解密,请检查您在银联开放平台(open.unionpay.com)上提供的RSA公钥是否正确
9915 您的API调用额度已耗尽,需充值付费后补充调用额度
9916 您的API并发调用额度已耗尽,需联系管理员调整您的并发限额
9917 您的账号不具备当前产品API请求权限,请联系相关业务接口人。
9991 银联开放平台系统内部错误:产品服务调用失败
9992 银联开放平台系统内部错误:产品服务系统未知错误
9993 银联开放平台系统内部错误:产品服务未注册至服务中心
9994 银联开放平台系统内部错误:产品服务参数错误

1. “快速接入”产品API使用教程请参考在线文档:

“快速接入”产品API指南—接入指南


2. “快速接入”产品API安全调用过程请参考在线文档:

2.1“快速接入”产品API指南—获取产品token

2.2快速接入”产品API指南—产品功能接口调用


3. “快速接入”产品API接口调用报文签名样例请参考在线文档:

“快速接入”产品API指南—报文签名样例代码


4. “快速接入”产品API测试工具使用说明请参考在线文档:

“快速接入”产品API指南—“快速接入”测试工具

常见问题
1. 请求API中的地区字段(organizer)取值有哪些?
解答详情:

1-浙江银联 3-福建银联 5-青岛银联 7-大连银联 9-湖北银联 11-安徽银联 13-河北银联 15-山西银联 17-深圳银联 19-青海银联 21-陕西银联 23-银联总公司 25-上海银联 29-厦门银联 31-河南银联 33-四川银联 35-辽宁银联 37-宁波银联 39-湖南银联 41-西藏银联 43-山东银联 45-广西银联 47-重庆银联

2. 请求API中的权益类别(bussType)取值有哪些?
解答详情:

00-普通权益

01-洗车权益

03-市内停车权益

04-代驾权益

05-CIP权益

06-机场停车权益(陕西)

07-加油权益

08-运动权益

09-智慧停车权益 

10-话费充值权益

11-商城权益(浙江)

12-签证权益

13-机场停车权益(浙江)


3. 调用接口返回提示 {"respMsg":"body or sign is null.","respCd":"9905"}
解答详情:

API接口需使用body部分传送JSON数据,故而HTTP请求的content-type需使用application/json,而不是application/x-www-form-urlencoded。

咨询我们
业务咨询
姓名: 汪一凡
电话: 021-20631629
邮箱: wangyifan1@unionpay.com
技术咨询
姓名: 林英觉
电话: 021-20633157
邮箱: linyingjue@unionpay.com
热门推荐