聚合鉴权¶

鉴权结果说明¶

聚合鉴权会同步返回服务调用结果，但鉴权结果可能会同步返回，也可能需等待异步通知，具体方式参见各接口说明。若无同步鉴权结果，请调用验证结果获取接口主动获取结果，或等待聚合鉴权的推送。
返回码 return_code 和返回描述 return_message 仅表示本次调用是否成功，并非鉴权结果。
认证结果代码 resp_code 和认证结果描述 resp_info 表示本次请求的认证结果。
在涉及图像比对时，通常认证结果含比对分值项 mp_ssim ，当分值大于聚合鉴权设定的阈值时 (如 60分)，聚合鉴权返回认证结果为成功，否则为失败。调用方如有需要，可自定义阈值，从而达到收紧或放松认证结果的目的。

调用地址说明¶

以下文档中涉及的调用地址均为生产环境。
调用地址为 https://aggrauth.adapay.tech/api/

返回码说明¶

返回码为 5 位的数字，前 3 位表示接口编号，后 2 位表示返回信息。 1~8 开头表示仅该接口出现的返回信息，后 2 位 00~09 时表示成功返回，10~99 时表示失败返回。 9 开头表示所有接口都可能出现的公共返回信息，90000~90009 表示成功返回，90100~91099 表示错误返回。

接口编号：

编号	服务名
102	银行卡实名认证
104	身份证实名认证

公共返回码：

返回码	说明
90101	参数错误，认证失败
90102	验证签名错误，认证失败
90103	没有使用此接口的权限，认证失败
90104	重复请求，认证失败
90105	操作过于频繁，认证失败
90199	未知原因，认证失败

银行卡实名认证返回码：

返回码	说明
10200	请求成功
10201	请求成功，需等待异步结果
10210	请求失败

身份证实名认证返回码：

返回码	说明
10400	请求成功
10410	请求失败

获取认证结果返回码：

返回码	说明
20000	请求成功
20010	认证失败
20011	没有查询到该笔验证
20012	该笔正在验证中

公共参数¶

所有接口均含公共参数，为减少冗余，单独提出。

公共请求参数¶

名称	类型	必填	描述
order_date	String	Y	请求日期
order_id	String	Y	订单号，请求唯一标识
app_token	String(40)	Y	用户标识，由聚合鉴权系统分配
sign	String	Y	参考服务调用说明-签名

公共响应参数¶

参数	类型	必填	描述
data	String	Y	返回数据
signature	String	Y	证书校验签名

data 数据结构中包含以下返回字段:

参数	类型	必填	描述
return_code	String	Y	返回码
return_message	String	N	返回描述
realme_date	String	Y	聚合鉴权系统日期
seq_id	String	N	聚合鉴权系统流水，本次交易唯一标识
order_date	String	Y	请求日期，原样返回
order_id	String	Y	订单号，请求唯一标识，原样返回

银行卡实名验证¶

接口说明¶

支持银行卡号、姓名、身份证号和手机号四要素验证；银行卡号、姓名和身份证号三要素验证；银行卡号、姓名二要素验证。
可能同步即有结果，也可能需等待异步结果通知，这取决于验证的要素和各银行的验证方式。可调用验证结果获取接口 GET /v4/checkresult 获取验证结果。
银行卡实名验证联调环境 mock 逻辑：返回验证结果只和身份证号码有关，当身份证号码以 1~7 开头时，均返回验证一致；以 8~9 开头时，均返回验证不一致。

HTTP Request

POST https://aggrauth.adapay.tech/api/v1/trade/cardcheck

请求参数¶

参数	类型	必填	描述
full_name	String	Y	姓名
id_number	String(18)	N	客户身份证号
mobile_no	String(11)	N	客户手机号
acct_no	String	Y	客户银行卡号
acct_type	String	N	账户类型：E-对公；P-对私
card_type	String	N	卡类型：D-借记卡；C-信用卡；P-存折； V-虚拟账户；Y-预付费卡；Z-借贷合一卡
valid_date	String	N	有效期，mmyy格式，信用卡非空
cvv2	String	N	信用卡非空，以加密方式传输
bank_identity	String	N	银行标识
source_channel	String	Y	来源渠道：0-PC；1-Android；2-iOS
imei	String	N	设备号
mer_bg_url	String	N	异步通知回调地址，以有效的 http:// 或者 https:// 开头
authorization_info	String	N	用户授权标识

响应参数¶

参数	类型	必填	描述
resp_code	String	N	认证结果代码：00-成功 (一致) ；01-失败 (不一致) ；99-异常
resp_info	String	N	认证结果描述

异步返回结果¶

参数	类型	必填	描述
resp_code	String	Y	认证结果
resp_info	String	Y	认证结果描述
full_name	String	Y	姓名

调用示例¶

shell

curl -H "env:test" -d "order_date=20170101&order_id=201701010000001&app_token=apptoken&sign=9F28CB5B52CAA8267314A9BAF7E6706E&..." https://aggrauth.adapay.tech/api/v1/trade/cardcheck

Java

String result = new String();
HttpClient client = new DefaultHttpClient();
HttpPost post = new HttpPost("https://aggrauth.adapay.tech/api/v1/trade/cardcheck");
try {
   List<NameValuePair> nvps = new ArrayList<NameValuePair>();
   nvps.add(new BasicNameValuePair("order_date", "20170101"));
   nvps.add(new BasicNameValuePair("order_id", "201701010000001"));
   nvps.add(new BasicNameValuePair("app_token", "apptoken"));
   nvps.add(new BasicNameValuePair("sign", "9F28CB5B52CAA8267314A9BAF7E6706E"));
   .......
   post.setEntity(new UrlEncodedFormEntity(nvps));
   post.addHeader("env", "test");
    HttpResponse httpResponse = client.execute(post);
   int code = httpResponse.getStatusLine().getStatusCode();
   String returnStr = EntityUtils.toString(httpResponse.getEntity());
        } catch (Exception e) {
                e.printStackTrace();
        }

Python

url = ''.join(['https://realme.cloudpnr.com', '/realme-api/v4/trade/cardcheck'])
      params = {'order_date': '20170101',
                   'order_id': '201701010000001',
                   'app_token': 'apptoken',
                   'sign': '9F28CB5B52CAA8267314A9BAF7E6706E',
                   ......
                   }
response = requests.post(url, params=params, headers={'env':'test'})

成功响应

200
{
 "data": "{"return_code": "10201", "return_message": "请求成功，需等待异步结果", "realme_date": "20170101", "seq_id": "2017010100000001",  "order_date": "20170101", "order_id": "201701010000001" }",
 "signature": "iZTuuTe2AmMmoxMeus7VJHz0TFntWXaC28YSPLQFYv6SLokhQ4aSSvi0b3oM6WNLrTZLfqQpB2dcX1rrstJiy+p0pOJDimcf8DoRI8FzPGIhNX5PlgJeYnffP6r/OsHqmjlv+lyYwmOS2LzBqdtTZ7IK9+W4jL4fvFyWCv2mGKo="
}

失败响应

400
{
   "data": '{"return_code": "90101","return_message": "参数校验失败"}',
   "signature": "iZTuuTe2AmMmoxMeus7VJHz0TFntWXaC28YSPLQFYv6SLokhQ4aSSvi0b3oM6WNLrTZLfqQpB2dcX1rrstJiy+p0pOJDimcf8DoRI8FzPGIhNX5PlgJeYnffP6r/OsHqmjlv+lyYwmOS2LzBqdtTZ7IK9+W4jL4fvFyWCv2mGKo="
 }

身份证实名认证¶

接口说明¶

通过采集用户姓名和身份证号信息，与公安系统进行数据一致性比对，完成身份验证。
同步返回验证结果。

HTTP Request

POST https://aggrauth.adapay.tech/api/v1/trade/namecheck

请求参数¶

参数	类型	必填	描述
full_name	String	Y	姓名
id_number	String(18)	Y	用户身份证号
source_channel	String	Y	来源渠道：0-PC；1-Android；2-iOS
imei	String	N	设备号
authorization_info	String	N	用户授权标识

响应参数¶

参数	类型	必填	描述
resp_code	String	N	认证结果代码：00-成功(一致)； 01-失败(不一致)； 99-异常
resp_info	String	N	认证结果描述

调用示例¶

shell

curl -H "env:test" -d "order_date=20170101&order_id=201701010000001&app_token=apptoken&sign=9F28CB5B52CAA8267314A9BAF7E6706E&..." https://aggrauth.adapay.tech/api/v1/trade/namecheck

Java

String result = new String();
HttpClient client = new DefaultHttpClient();
HttpPost post = new HttpPost("https://aggrauth.adapay.tech/api/v1/trade/namecheck");
try {
   List<NameValuePair> nvps = new ArrayList<NameValuePair>();
   nvps.add(new BasicNameValuePair("order_date", "20170101"));
   nvps.add(new BasicNameValuePair("order_id", "201701010000001"));
   nvps.add(new BasicNameValuePair("app_token", "apptoken"));
   nvps.add(new BasicNameValuePair("sign", "9F28CB5B52CAA8267314A9BAF7E6706E"));
   .......
   post.setEntity(new UrlEncodedFormEntity(nvps));
   post.addHeader("env", "test");
    HttpResponse httpResponse = client.execute(post);
   int code = httpResponse.getStatusLine().getStatusCode();
   String returnStr = EntityUtils.toString(httpResponse.getEntity());
        } catch (Exception e) {
                e.printStackTrace();
        }

Python

url = ''.join(['https://realme.cloudpnr.com', '/realme-api/v4/trade/namecheck'])
      params = {'order_date': '20170101',
                   'order_id': '201701010000001',
                   'app_token': 'apptoken',
                   'sign': '9F28CB5B52CAA8267314A9BAF7E6706E',
                   ......
                   }
response = requests.post(url, params=params, headers={'env':'test'})

成功响应

 200
 {
  "data": "{"return_code": "10400", "return_message": "成功", "realme_date": "20170101", "seq_id": "2017010100000001", "order_date": "20170101", "order_id": "201701010000001", "resp_code": "00", "resp_info": "认证通过"}",
  "signature": "iZTuuTe2AmMmoxMeus7VJHz0TFntWXaC28YSPLQFYv6SLokhQ4aSSvi0b3oM6WNLrTZLfqQpB2dcX1rrstJiy+p0pOJDimcf8DoRI8FzPGIhNX5PlgJeYnffP6r/OsHqmjlv+lyYwmOS2LzBqdtTZ7IK9+W4jL4fvFyWCv2mGKo="
}

失败响应

 400
 {
  "data": "{"return_code": "90101","return_message": "参数校验失败"}",
  "signature": "iZTuuTe2AmMmoxMeus7VJHz0TFntWXaC28YSPLQFYv6SLokhQ4aSSvi0b3oM6WNLrTZLfqQpB2dcX1rrstJiy+p0pOJDimcf8DoRI8FzPGIhNX5PlgJeYnffP6r/OsHqmjlv+lyYwmOS2LzBqdtTZ7IK9+W4jL4fvFyWCv2mGKo="
}

验证结果获取¶

接口说明¶

本接口用于查询认证结果。
聚合鉴权支持两种查询方式，以聚合鉴权流水号 seq_id 查询和以调用方订单号 order_id 查询。seq_id 为原认证请求发起时，聚合鉴权返回的流水号，在 seq_id 非空时，优先以 seq_id 查询。若当时未收到聚合鉴权应答，请将 seq_id 填空，并将公共参数中的 order_id 值填为原认证请求的 order_id (此时请确保 order_id 值唯一) 。

HTTP Request

GET https://aggrauth.adapay.tech/api/v1/checkresult

请求参数¶

名称	类型	是否必须	限制	描述
seq_id	String	否		聚合鉴权返回的流水号

响应参数¶

参数	类型	是否非空	描述
resp_code	String	否	认证结果代码：00-成功(一致)； 01-失败(不一致)；99-异常
resp_info	String	否	应答信息
mp_ssim	String	否	比对分值，0-100
full_name	String	否	姓名
id_number	String	否	身份证号
file_list	List	否	文件列表
face_identify_list	List	否	相似用户列表
authorization_info	String	否	用户授权标识

其中 file_list：

参数	类型	是否非空	描述
file_id	String	是	图片 id
file_type	String	是	图片类型：00-人像照片； 01-身份证正面照； 02-身份证反面照
file_source	String	是	图片来源：IFS-汇付内部文件地址 (不对外开放)；JVS-聚合鉴权文件地址 (可通过聚合鉴权文件服务接口下载)

其中 face_identify_list :

参数	类型	是否非空	描述
personId	String	是	图片 id
fileId	String	是	jfile的文件 ID
personName	String	是	姓名
score	String	是	相似度评分

调用示例¶

shell

curl -H "env:test" -d "order_date=20170101&order_id=201701010000001&app_token=apptoken&sign=9F28CB5B52CAA8267314A9BAF7E6706E&seq_id=20170101000005" https://aggrauth.adapay.tech/api/v1/checkresult

Java

  String result = new String();
  HttpClient client = new DefaultHttpClient();
  HttpPost post = new HttpPost("https://aggrauth.adapay.tech/api/v1/checkresult");
  try {
     List<NameValuePair> nvps = new ArrayList<NameValuePair>();
     nvps.add(new BasicNameValuePair("order_date", "20170101"));
     nvps.add(new BasicNameValuePair("order_id", "201701010000001"));
     nvps.add(new BasicNameValuePair("app_token", "apptoken"));
     nvps.add(new BasicNameValuePair("sign", "9F28CB5B52CAA8267314A9BAF7E6706E"));
     .......
     post.setEntity(new UrlEncodedFormEntity(nvps));
     post.addHeader("env", "test");
HttpResponse httpResponse = client.execute(post);
     int code = httpResponse.getStatusLine().getStatusCode();
     String returnStr = EntityUtils.toString(httpResponse.getEntity());
} catch (Exception e) {
  e.printStackTrace();
}

Python

url = ''.join(['https://aggrauth.adapay.tech', '/api/v1/checkresult'])
      params = {'order_date': '20170101',
                   'order_id': '201701010000001',
                   'app_token': 'apptoken',
                   'sign': '9F28CB5B52CAA8267314A9BAF7E6706E',
                   ......
                   }
response = requests.get(url, params=params, headers={'env':'test'})

成功响应

 200
 {
  "data": "{"return_code": "20000","return_message": "成功","realme_date": "20170101","seq_id" : "2017010100000001","order_date": "20170101","order_id": "201701010000001","resp_code": "00","resp_info": "认证通过","mp_ssim": "60","full_name": "","id_number": "","encrypt_method" : "00","file_list" :[{"file_id": "J20170504123698547","file_type": "01","file_source": "JVS"}]}",
  "signature": "iZTuuTe2AmMmoxMeus7VJHz0TFntWXaC28YSPLQFYv6SLokhQ4aSSvi0b3oM6WNLrTZLfqQpB2dcX1rrstJiy+p0pOJDimcf8DoRI8FzPGIhNX5PlgJeYnffP6r/OsHqmjlv+lyYwmOS2LzBqdtTZ7IK9+W4jL4fvFyWCv2mGKo="
}

失败响应

400
{
  "return_code": "90101",
  "return_message": "参数校验失败"
}

验证结果通知¶

接口说明¶

此接口由聚合鉴权主动发起，发送方式同异步通知，无需请求，公共字段在此接口中无效。
通知接收地址即为调用接口服务时，请求参数中的 mer_bg_url 字段，请保证其在公网中可正常访问。
接收方式同接收异步通知，参数参考API文档各个接口的 “异步返回结果”。

请求参数¶

参数	类型	是否非空	描述
seq_id	String	是	聚合鉴权流水号
order_id	String	是	商户订单号
return_code	String	是	返回结果代码
return_message	String	否	返回结果描述
resp_code	String	否	认证结果代码：00-成功(一致)； 01-失败(不一致)；99-异常
resp_info	String	否	应答信息
mp_ssim	String	否	比对分值，0-100
full_name	String	否	姓名
id_number	String	否	身份证号
file_list	List	否	文件列表
sign	String	是	签名
face_identify_list	List	否	相似用户列表

其中 file_list：

参数	类型	是否非空	描述
file_id	String	是	图片 id
file_type	String	是	图片类型：00-人像照片； 01-身份证正面照； 02-身份证反面照
file_source	String	是	图片来源：IFS-汇付内部文件地址 (不对外开放)；JVS-聚合鉴权文件地址 (可通过聚合鉴权文件服务接口下载)

其中 face_identify_list :

参数	类型	是否非空	描述
personId	String	是	图片 id
fileId	String	是	jfile的文件 ID
personName	String	是	姓名
score	String	是	相似度评分