银行卡信息三要素认证-001031000
<p>[TOC]</p>
<h5>1.<strong>使用说明</strong></h5>
<p>1.1 数据格式
服务请求采用HTTPS协议，用户需以HTTPS POST方式传输给服务端；传输参数的报文串以JSON数据串传输，编码格式为UTF-8；请严格依照参数规范设置参数，切勿遗漏“必填”参数，注意大小写区分
1.2 服务访问地址
测试环境: <a href="https://[ip地址或主机名]:[端口号]/api/v1/app/test/authservice">https://[ip地址或主机名]:[端口号]/api/v1/app/test/authservice</a>
生产环境: <a href="https://[ip地址或主机名]:[端口号]/api/v1/app/authservice">https://[ip地址或主机名]:[端口号]/api/v1/app/authservice</a>
所有服务访问相同的的地址。
1.3 消息体定义
请求消息的格式样例如下：</p>
<pre><code>{
"meta": {
"account": "XXX",
"service_code": "001040100",
"request_sn": "48982789438392929",
"timestamp": 1535622793245,
"sign": "64cd46e5f879232389003e5564c6e44e"
},
"params": {
"name": "XXX",
"id_no": "XXX"
}
}</code></pre>
<p>请求消息体分为两部份，meta内是认证和服务号参数，params内是服务号对应的输入参数，输入参数需根据相应的服务类型设置。
请求参数说明如下：</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>account</td>
<td>String</td>
<td>必填</td>
<td>账号名</td>
</tr>
<tr>
<td>service_code</td>
<td>String</td>
<td>必填</td>
<td>服务号编码，每个服务类对应一个编码</td>
</tr>
<tr>
<td>timestamp</td>
<td>Long</td>
<td>必填</td>
<td>时间戳</td>
</tr>
<tr>
<td>request_sn</td>
<td>String</td>
<td>必填</td>
<td>调用方生成的唯一请求流水号，不超过40位</td>
</tr>
<tr>
<td>timestamp</td>
<td>Long</td>
<td>必填</td>
<td>请求签名，具体签名规则详见1.4节</td>
</tr>
</tbody>
</table>
<p>响应消息体也分为两部份，meta内是响应结果和相关元数据，data内是返回的数据，不同的服务类型的返回数据请参照相关服务的接口章节。
返回消息的格式样例如下：</p>
<pre><code>{
"meta": {
"service_code": "001040100",
"result_code": "200",
"result_desc": "查询成功"
},
"data": {
"result": "XXX",
"name": "XXX",
"id_no": "XXX",
"birthday": "XXX",
"gender": "XXX"
}
}</code></pre>
<p>返回数据说明如下：</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>service_code</td>
<td>String</td>
<td>必填</td>
<td>服务号编码，每个服务类对应一个编码</td>
</tr>
<tr>
<td>result_code</td>
<td>String</td>
<td>必填</td>
<td>返回结果码，详情请参照下表</td>
</tr>
<tr>
<td>result_desc</td>
<td>Long</td>
<td>必填</td>
<td>返回结果描述</td>
</tr>
</tbody>
</table>
<p>返回码的定义如下：</p>
<table>
<thead>
<tr>
<th>返回码</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>查询成功</td>
</tr>
<tr>
<td>204</td>
<td>查询成功且无内容</td>
</tr>
<tr>
<td>400</td>
<td>输入参数错误</td>
</tr>
<tr>
<td>401</td>
<td>未授权账户</td>
</tr>
<tr>
<td>402</td>
<td>系统该服务已达每日调用上限</td>
</tr>
<tr>
<td>403</td>
<td>该账户此服务已达每日调用上限</td>
</tr>
<tr>
<td>404</td>
<td>服务不支持</td>
</tr>
<tr>
<td>407</td>
<td>IP地址受限</td>
</tr>
<tr>
<td>408</td>
<td>签名错误</td>
</tr>
<tr>
<td>409</td>
<td>请求超时</td>
</tr>
<tr>
<td>500</td>
<td>内部执行异常</td>
</tr>
<tr>
<td>504</td>
<td>数据查询异常</td>
</tr>
</tbody>
</table>
<p>1.4 签名算法</p>
<ul>
<li>
<p>为了保证传输数据的真实性与有效性，调用方需对请求数据签名，我方在接收请求后会进 行签名校验，校验失败将拒绝请求。
签名过程主要分为两个步骤：
1)生成需要签名的原始字符串；
2)使用摘要算法计算原始字符摘要信息作为签名；</p>
</li>
<li>a)签名原始字符串
签名原始字符串 = 账号 + 请求流水号 + 服务号 + 时间戳 + 密码
假设已知请求参数如下：
String account= "testsign";
String request_sn = "48982789438392929";
String service_code= "001001000";
Long timestamp = 1535622793245;
String password= "3GepGpfcvPaVtNKuaCy1";
则签名原始字符串为:
String signStr = account+ request_sn+ service_code+ timestamp +password;
计算结果即：
testsign4898278943839292900100100015356227932453GepGpfcvPaVtNKuaCy1</li>
<li>b)签名计算
原始字符串生成好之后需要计算其摘要信息作为签名，使用MD5算法</li>
<li>c)生成的原始字符串的签名计算方法为：
String signature = md5(signStr)
计算结果signature则为签名。
签名为:cb6cc0fb2fa6dc97f5b4d18b9ad53b6f</li>
</ul>
<h5>2.<strong>安全策略</strong></h5>
<p>数据传输采用HTTPS的TLS/SSL方式加密解密，客户端请求服务时会从服务端获取服务端的公钥，然后客户端使用服务端公钥加密数据发送给服务端，服务端收到加密数据后，使用服务端的私钥解密数据和处理请求。考虑到服务端的证书有可能是self sign的，所以客户端在收到服务端公钥时不对该公钥做验证；</p>
<h5>3.<strong>测试信息</strong></h5>
<p>测试接口对接时需要知道服务器访问地址，账号和密码，请与中新金科联系开通账号。</p>
<h5>4.<strong>接口规范：（服务号001031000）</strong></h5>
<p>4.1 说明
验证银行卡信息三要素认证接口
4.2 请求消息样例</p>
<pre><code>{
"meta": {
"account": "xxxx",
"service_code": " 001031000",
"request_sn": "48982789438392929",
"timestamp": 1535622793245,
"sign": "64cd46e5f879232389003e5564c6e44e"
},
"params": {
"name": "xx",
"id_no": "13018xxxxx042",
"bank_acct": "2156xxxxx465",
"request_sn": "48982789438392929"
}
}</code></pre>
<p>4.3 请求参数说明</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>String</td>
<td>必填</td>
<td>公民姓名</td>
<td></td>
</tr>
<tr>
<td>id_no</td>
<td>String</td>
<td>必填</td>
<td>对应姓名的身份证号码</td>
<td></td>
</tr>
<tr>
<td>bank_acct</td>
<td>String</td>
<td>必填</td>
<td>银行卡号</td>
<td></td>
</tr>
<tr>
<td>is_encrypt</td>
<td>String</td>
<td>选填</td>
<td>输入信息是否AES加密 0否/1是,默认不加密</td>
<td>密钥为使用账户所对应的密码,加解密方法详见4.6代码示例</td>
</tr>
<tr>
<td>request_sn</td>
<td>String</td>
<td>选填</td>
<td>调用方请求流水号，非空时返回信息中会包含流水号信息</td>
<td>不超过40位</td>
</tr>
</tbody>
</table>
<p>4.4 同步返回消息样例
返回消息样例格式如下:</p>
<pre><code>{
"meta": {
"service_code": " 001031000",
"result_code": "200",
"result_desc": "查询成功"
},
"data": {
"res_code": "0000",
"res_desc": "认证成功",
"request_sn": "48982789438392929"
}
}</code></pre>
<p>4.5 返回参数说明</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>res_code</td>
<td>String</td>
<td>选填</td>
<td>认证结果码</td>
<td></td>
</tr>
<tr>
<td>res_desc</td>
<td>String</td>
<td>选填</td>
<td>认证结果</td>
<td></td>
</tr>
<tr>
<td>charge</td>
<td>Boolean</td>
<td>必填</td>
<td>收费标识:true收费/false</td>
<td></td>
</tr>
<tr>
<td>request_sn</td>
<td>String</td>
<td>选填</td>
<td>调用方请求流水号</td>
<td>不超过40位</td>
</tr>
</tbody>
</table>
<p>认证结果码的说明如下：</p>
<table>
<thead>
<tr>
<th>返回码</th>
<th>说明</th>
<th>备注</th>
<th>是否收费</th>
</tr>
</thead>
<tbody>
<tr>
<td>0000</td>
<td>认证成功</td>
<td>验证一致</td>
<td>是</td>
</tr>
<tr>
<td>1302</td>
<td>交易通讯超时</td>
<td>系统异常</td>
<td>否</td>
</tr>
<tr>
<td>2311</td>
<td>风险受限(黑名单)</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>2314</td>
<td>无效卡号</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>2316</td>
<td>卡状态不正常</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>2318</td>
<td>输入的密码、有效期或CVN2 有误，交易失败</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>2319</td>
<td>验证不一致</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>2320</td>
<td>密码输入次数超限</td>
<td>不支持验证</td>
<td>是</td>
</tr>
<tr>
<td>2321</td>
<td>您的银行卡暂不支持该业务</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>2325</td>
<td>交易失败或银行拒绝交易,请联系发卡行</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>2344</td>
<td>您的银行卡未预留手机号</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>2345</td>
<td>您的手机未开通无卡支付服务</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>2400</td>
<td>卡状态不正常(睡眠卡/未初始化卡)</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>2401</td>
<td>卡状态不正常(过期卡)</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>2402</td>
<td>卡状态不正常(挂失卡)</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>2403</td>
<td>卡状态不正常(被窃卡)</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>4001</td>
<td>无效卡</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>4003</td>
<td>无效证件号</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>4004</td>
<td>无效手机号</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>4005</td>
<td>无效姓名</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>4006</td>
<td>多种要素格式错误</td>
<td>验证要素格式有误</td>
<td>否</td>
</tr>
<tr>
<td>4007</td>
<td>非银行预留手机号</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>4008</td>
<td>只支持中国移动手机号码</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>5101</td>
<td>该卡交易过于频繁,请稍后重试</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>5103</td>
<td>该卡今日重复验证次数过多,请明日重试</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>5105</td>
<td>短期内有同卡重复交易,请稍后重试</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>5106</td>
<td>验证信息不存在</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>5107</td>
<td>无数据</td>
<td>不支持验证</td>
<td>否</td>
</tr>
<tr>
<td>1399</td>
<td>后台系统未知错误</td>
<td>系统异常</td>
<td>否</td>
</tr>
</tbody>
</table>
<p>4.6 加解密代码</p>
<pre><code>import java.nio.charset.StandardCharsets;
import javax.crypto.Cipher;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class ZxAesUtils {
加解密代码示例
private static final Logger log = LoggerFactory.getLogger(ZxAesUtils.class);
private static final String PADDING_SCHEME = "AES/ECB/PKCS5Padding";
private static final String ALGORITHM = "AES";
private static final String ALIGN = "0000000000000000";
/**
* 加密
* @param src
* @param key
* @return
*/
public static String encrypt(String src, String key)
{if (key == null || key.trim().isEmpty()) {
log.info("key must not be empty");
return null;
}
if (src == null || src.trim().isEmpty())
{ log.info("src must not be
empty");return null;
}
byte[] raw = align(key);
SecretKeySpec keySpec = new SecretKeySpec(raw, ALGORITHM);
try {
Cipher cipher = Cipher.getInstance(PADDING_SCHEME);
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
byte[] encrypted = cipher.doFinal(src.getBytes());
return Base64.encodeBase64String(encrypted);
} catch (Exception e) {
log.warn("{}", e.getMessage(), e);
return null;
}
}
/**
* 解密
* @param src
* @param key
* @return
* @throws Exception
*/
public static String decrypt(String src, String key) {if (key == null || key.trim().isEmpty() || src == null || src.trim().isEmpty())
{log.info("key and src must not be empty");
return null;
}
byte[] raw = align(key);
SecretKeySpec keySpec = new SecretKeySpec(raw, ALGORITHM);
try {
Cipher cipher = Cipher.getInstance(PADDING_SCHEME);
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] encrypted = Base64.decodeBase64(src);
byte[] original = cipher.doFinal(encrypted);
return new String(original, StandardCharsets.UTF_8);
} catch (Exception e) {
log.warn("{}", e.getMessage(), e);
return null;
}
}
/**
* key 补位
* @param key
* @return
*/
private static byte[] align(String key)
{byte[] data;
if (key.length() >= 16) {
data = key.substring(0, 16).getBytes(StandardCharsets.UTF_8);
} else {
int plus = 16 - key.length();
String s = key + ALIGN.substring(0, plus);
data = s.getBytes(StandardCharsets.UTF_8);
}
return data;
}
public static void main(String[] args) {
/* 加密key 为帐户对应密码，此处"123"仅作示例 */String
key = "123";
String data = "abc";
long start = System.currentTimeMillis();
log.info("start:{}", start);String encrypt = encrypt(data, key);
log.info("used:{}", System.currentTimeMillis()-start);
log.info("encrypt:{}", encrypt);
start = System.currentTimeMillis();
String decrypt = decrypt(encrypt, key);
log.info("used:{}", System.currentTimeMillis()-start);
log.info("decrypt:{}", decrypt);
}
}</code></pre>