2018-08-22:更新商户角色输出字段
2018-07-18:按不同申请人身份将返回字段进行划分说明
2018-05-08:修改接口名称为 交易安全防护(普惠版)
2017-11-02:增加请求方式的说明
2017-09-30:risktype枚举增加赌博、疑似欺诈、疑似赌博
商户风险交易推送:
应用场景:基于强大的数据沉淀和精准的风险识别能力,主动向支付宝合作伙伴提供风险交易推送服务。风险类型主要包括欺诈、赌博、虚假交易,协助合作伙伴识别交易风险,助力合作伙伴业务健康发展。
请求地址:
环境 | 商户网关地址 |
---|---|
正式环境 | 银行接收商户风险交易推送的地址 |
请求方式 | POST |
推送风险内容:
我们会依据您申请服务的PID和进行的交易类型,推送给您不同的风险交易信息。
请在收到推送通知并且验签通过后,返回支付宝 success 七个字符。
环境 |
商户网关地址 |
正式环境 |
银行接收商户风险交易推送的地址 |
请求方式 |
POST |
参数 |
类型 |
是否必填 |
最大长度 |
参数描述 |
示例值 |
service |
String |
是 |
128 |
服务出口网关名 |
alipay.riskgo.risk.push |
sign_type |
String |
是 |
10 |
签名方式(RSA或RSA2) |
RSA2 |
sign |
String | 是 | 1024 | 签名值 | |
charset |
String |
是 |
10 |
请求的编码格式,返回的响应 |
GBK |
参数 |
类型 |
是否必填 |
最大长度 |
参数描述 |
示例值 |
smid |
String |
否 |
40 |
涉嫌风险子商户在支付宝被分配的商户ID |
2088256325102154 |
pid |
String |
否 |
40 |
申请业务合作伙伴ID |
2088765523456679 |
externalId |
String |
否 |
128 |
涉嫌风险子商户在银行被分配的商户ID |
101530278966 |
sourceId |
String |
否 |
40 |
风险子商户对应的服务商ID |
2088121907460882 |
tradeNos |
String |
否 |
128 |
风险交易号样例(由于风险识别策略差异,个别情况,无风险交易号样例) |
201705090000000001wd2 |
alipayTradeNos |
String |
否 |
40 |
支付宝流水号 |
201911019298383288282 |
bank_card_no | String | 否 | 40 | 银行卡号 | 6228480402637874212 |
risktype |
String |
是 |
40 |
风险类型 |
欺诈、赌博、套现、套费率 |
risklevel |
String |
是 |
40 |
风险情况描述 |
欺诈风险(欺诈风险极高,且有投诉) |
riskDesc | String | 否 | 1024 | 风险定位原因说明 | 套费率:例如:买卖家关系异常 |
参数 |
类型 |
是否必填 |
最大长度 |
参数描述 |
示例值 |
smid |
String |
是 |
40 |
涉嫌风险子商户在支付宝被分配的商户ID |
2088256325102154 |
pid |
String |
是 |
40 |
申请业务合作伙伴ID |
2088123407460882 |
externalId |
String |
否 |
128 |
涉嫌风险子商户在银行被分配的商户ID |
101530278966 |
sourceId |
String |
是 |
40 |
风险子商户对应的服务商ID |
2088121907460882 |
tradeNos |
String |
否 |
128 |
风险交易号样例(由于风险识别策略差异,个别情况,由于无风险交易号样例) |
201705090000000001wd2 |
alipayTradeNos |
String |
否 |
40 |
支付宝流水号 |
201911019298383288282 |
bank_card_no |
String |
否 |
40 |
银行卡号 |
6228480402637874212 |
risktype |
String |
是 |
40 |
风险类型 |
欺诈、赌博、套现、套费率 |
risklevel |
String |
是 |
40 |
风险情况描述 |
欺诈风险(欺诈风险极高,且有投诉) |
riskDesc | String | 否 | 1024 | 风险定位原因说明 | 套费率:例如:买卖家关系异常 |
参数 |
类型 |
是否必填 |
最大长度 |
参数描述 |
示例值 |
pid |
String |
是 |
40 |
申请业务合作伙伴ID |
2088123407460882 |
merchantId |
String |
否 |
40 |
涉嫌风险商户的PID 虚假交易场景下此字段代表有风险的服务商服务商小二的账户ID |
2088765523456679 |
tradeNos |
String |
否 |
128 |
商户风险交易号 (由于风险识别策略差异,个别情况,无风险交易号样例) |
201705090000000001wd2 |
alipayTradeNos |
String |
否 |
40 |
支付宝流水号 |
201911019298383288282 |
risktype |
String |
否 |
40 |
风险类型 |
虚假交易 |
risklevel |
String |
是 |
40 |
风险情况描述 |
欺诈、赌博、套现、虚假交易 |
riskDesc |
String |
否 |
1024 |
风险定位原因说明 |
风险类型:虚假交易: 商户整体虚假交易原因:
虚假交易金额(分):100.0; 虚假交易占比:1.0; 本笔交易虚假交易原因:
近一周作业商家数:32; 风险商家数:2; 总交易笔数:275; 风险交易笔数:67; 风险类型:套费率: 例如:买卖家关系异常 |
参数 |
类型 |
是否必填 |
最大长度 |
参数描述 |
示例值 |
pid |
String |
是 |
40 |
申请业务合作伙伴ID |
2088765523456679 |
appid |
String |
是 | 40 | 申请业务合作伙伴的应用ID | 2021001166689676 |
tradeNos |
String |
否 |
40 |
外部交易号 (个别情况,无风险交易号) |
201705090000000001wd2
|
risktype |
String |
是 |
40 |
风险类型 |
欺诈、赌博、套现、投诉 |
risklevel |
String |
是 |
40 |
风险情况描述 |
欺诈风险(欺诈风险极高,且有投诉) |
gmtOccur |
String |
是 | 40 | 推送时间(毫秒级时间戳) | 样例:1621834022775 |
complainTime |
String |
否 |
128 |
用户投诉时间 |
2018/8/19 23:40 备注:当risktype = “投诉”时才有内容 |
complainText |
String |
否 |
1024 |
用户投诉内容 |
付款成功后,没有开通会员 备注:当risktype = “投诉”时才有内容 |
三、常见FAQ
1,问 : 商户对接的1.0的即时到账、wap、app支付,非当面付,可以对接吗?
答 : 可以,接口独立跟支付产品不绑定。
2,问 : 商户收到推送消息后回传平台子账号相关信息给支付宝,商户把该交易对应账号信息(平台账号、IP、交易号等)同步给支付宝后,支付宝会做些什么处理?商户需要配合做些什么?
答 : 这些信息一方面是监管( 比如公安) 需要调单 和线下打击 ; 一方面风控用来数据分析, 以便传输更精准风险数据给商户。商户需要按流程发起邮件申请相关配置和权限,按文档引导线上测试即可。
3,问 : 我们有多个支付宝账号,是需要每个账号都要支付宝开放平台创建应用吗?
答 : 如无特殊需求,使用一个应用的APPID就可以了。应用主要用于调用风险数据回传接口。
那其他支付类型的PID的风险交易也会推送过来吗?
答 : 可以。关联认证的账号,只要一个配置过riskgo,其他pid下的风险交易也会一起推送到配置的推送地址上。
4,问 : 是什么场景下触发通知? 举例:是否商户端发起支付前还是什么?
答 : 都是成功的交易,支付宝识别风险成立后会马上推给商户。比如用户被骗来投诉后,我们会区分原因,比如欺诈成立,纠纷等等,然后把欺诈成立的这些交易推送给商户。
5,问 : 安全接口的使用场景和作用是什么?
答 : 应用场景是打击网络违法违规交易,主要是大家网络欺诈。 例如: 存在大量不法份子在商户端注册,利用平台进行下单,创建一些钓鱼链接或二维码 ,用来诱骗用户,造成用户损失。通过安全服务接口,双方进行联防联控,可以有效打击网络违法违规。
6,问 : 对推送的通知进行验签操作,出现验签失败的情况,可能的原因是什么?
答 : 如果是使用SDK来验签,请使用sdk封装好的验签方法:boolean AlipaySignature.rsaCheckV1(Map<String, String> params, String publicKey, String charset, String signType);确保验签函数的四个参数都是正确的,因为风控通知内容的编码是GBK,其中charset参数应该是GBK,sign_type参数根据邮件申请的配置填写RSA或RSA2,params直接传入遍历获取的所有post参数,publicKey传入支付宝平台上复制来的支付公钥.如果没有使用SDK,请参考文档上的异步通知验签步骤:https://docs.open.alipay.com/200/106120
7,问 : 推送的通知没有收到是什么原因?
答 : 通常原因都是密钥没有配置造成的,RSA2的密钥是在appid对应的应用下上传RSA(SHA256)密钥,并保存支付宝公钥留做验签.RSA的密钥是在开放平台设置mapi密钥. 如果申请了多个PID,需要在每个pid下面都配置对应的密钥选项.
8,问 : 收到风控通知后要多长时间内调用风险商户数据同步接口?
答 : 越快越好,最好一周内,对推送的风险交易做完处理后就应调用同步接口回传数据.如收到多次风险推送可回传多次。
9,问 : 风险商户数据同步接口中的trade_no参数需要传递商户订单号还是支付宝交易号?
答 : 目前该参数没有做强制校验,传递的值和通知里推送的tradeNos参数一致即可.通常在风险交易推送接口中tradeNos是外部订单号。
10,问 : 用来投诉的测试交易,金额一定要大于2元吗?
答 : 我们推荐使用riskgo.alipay.com平台自助联调功能,可支持沙箱、线上自助联调;如果是走的线下邮件申请需要做线上联调的,测试投诉交易金额需要大于2元,小于2元会被风控策略判断放过,测试完后,可以发起原路退款.
11,问 : 所有的风控通知都是通过用户投诉来触发的吗?用户投诉后,支付宝会核实用户的投诉是否成立吗?
答 : 既有通过用户投诉来触发的通知,也有风控模型分析出来的风险交易.目前推送的都是确定欺诈的,准确度99%以上.
12,问 : 风控处罚类型里的关停账户,是什么样的操作?
答 : 支付宝推送风控通知以后,你们需要查看交易背后对应的注册账户,核实风险后,关停这个商户在你们平台的账户.
13,问 : alipay.risk.end.push接口推送机制怎样
答 : alipay.risk.end.push这个接口只推送一次,拿到通知后没有返回success,不会重试推送.
14,问 : 邮件申请了不同的appID,接收到推送报文后用哪个appID的支付宝公钥验签
答 : 如果邮件申请的签名方式是rsa,那所有的账号对应的验签支付宝公钥都是相同的,如果签名方式是rsa2,那同一个PID下面的appID对应的验签支付宝公钥都是相同的。
15,问 : 想修改推送的网关地址
答:riskgo配置商户推送网关需要走很严格的审批,申请时请填写线上真实网关地址,不建议频繁修改。如不可避免需要重新配置,请在之前申请配置的邮件基础上,再发邮件并写明修改原因。
16,问 : 我验签的公钥从哪里获取 ?
答 : 目前使用RSA2的,直接使用原有的密钥加签、验签即可,无需任何变动。使用RSA的,需在开放平台设置mapi密钥,<交易安全防护(普惠版)>接口推送的报文需用此处的公钥进行验签。mapi秘钥配置入口。
17,问 : 推送接口验签方式 是对哪些数据验签?参数拼接示例怎样?
答 :除sign和signType不参与验签外,其他所有字段,都要参与验签,要使用黑名单的实现方式,而不是白名单,否则后续增加推送新的字段后,验签会无法通过。
参数格式举例:charset=GBK&pid=2088001969784501&risklevel=欺诈成立&risktype=欺诈&service=alipay.adatabus.risk.end.push&tradeNos=2017052421001004960267833397
18,问 : 推送接口编码格式都是GBK?
答:是的。目前只能是GBK,如果您的编码是其他的,在接收通知时需要做下转码。
19,问 : 回传的的业务参数中,账号名只能掩码提供不能提供明文,这个可以么?
答 : 可以的。
20,问 : 回传接口返回未知的错误码
答 : 入参bizcontent不是json字符串,请检查字符串格式以及回传内容。
21,问 : 回传接口异常sign check fail: check Sign and Data Fail!
答 : 同步验签失败,验签用的支付宝公钥不对。请登录开放平台到对应应用中查看支付宝公钥,重新配置。另需要注意使用的签名方法是RSA还是RSA2.支付宝公钥配置要与之对应。
22,问 : risktype和risklevel的参数值是中文汉字吗?编码是什么?
答 : 是中文汉字。编码为GBK。
23,问 : 收到的tradeNos中有多个交易号时,同步接口应该如何同步回传?应该是一笔一笔,还是一次性全部?
答 : 需要同步接口一笔一笔同步回传,同步接口仅支持单笔交易回传。
24,问 : 推送风险异步通知后,我们没有收到支付宝系统还会像支付通知一样24小时内重复推送吗?
答 : 不会重复推送。推送系统属于不同系统,目前仅推送一次若没有收到通知不会再重复推送。请保持接收网关正常访问。
25,问 : 同一笔交易号会出现多次推送吗?是否需要对交易号做幂等?
答 : 会出现多次推送的,交易号不要做幂等。
26,问 : 推送的异步通知Content-Type是application/json还是application/x-www-form-urlencoded?
答 : Content-Type: application/x-www-form-urlencoded