接口规范
注意事项
- 系统返回的应答或通知消息可能会由于升级增加参数,请验证通知签名或处理应答报文时注意允许这种情况。
- 应用密钥需要严格保密。如因开发者的应用密钥泄露而导致的安全问题,损失需要由开发者自行承担。
- 所有接口报文统一使用UTF-8编码。
- 本文档为接口接入指南,相应的交易或对应接口参数等信息,请参考产品介绍中的相应章节。
通讯方式
- 本系统与开发者间的通讯方式为HTTPS协议方式。
- 请求报文格式为application/x-www-form-urlencoded或application/json。
- 本系统返回给开发者的数据分为两种:当为普通报文时,HTTP头部Content-Type值为application/json,数据为JSON格式字符串;当为文件时,HTTP头部Content-Type值为application/octet-stream,数据为文件内容。
所有通信报文使用UTF-8编码。
流程图如下:
应用密钥
- 本系统采用标准的
SM3WithSM2
算法用于通讯间的签名、验签。 - 本系统使用SM2私钥作为应用密钥。以下为一个私钥的示例:
Q0upIqUatcyfTt97BXLA7LoMOyE/yKb/z3NOksLMbmk=
注意事项:
- 应用密钥请勿与测试环境密钥一致。
- 生产上建议定期更换应用密钥。
- 开发者需要严格保密自己的应用密钥,不能将应用密钥放置在可公开获取的地方,比如客户端中等。由于泄露应用密钥而导致的任何风险,需要开发者自行承担。
- 对于应用密钥,本系统服务器上没有保存副本,开发者若遗失,只能进行重置操作。
服务调用签名/字段加密算法
签名
开发者发送给本系统的所有请求,都需要进行签名,以确保是开发者系统发出的交易指令,具体的签名规则如下:
- 将有效的GET或POST参数组成“参数键=参数值”的格式,如order_amount=100;
- 将1步中所有的“参数键=参数值”按参数键以字典序进行排序;
- 使用英文半角的&符号将2步中排序后的字符串连接起来,如key1=value1&key2=value2…,注意字符串最后没有&
- 在字符串前部附加KEYID&TIMESTAMP&NONCE&METHOD&URI格式字符串,其中TIMESTAMP为当前时间,格式如 20160516120000;NONCE为请求随机数,需确保每次请求时不重复,最大长度为32,允许包含数字、大小写英文字母;METHOD为HTTP方法,使用大写,如GET、POST等;URI为当前请求的资源地址,如/v1/open(域名之后,?之前)等。拼装后的报文格式类似如下:
KY0123456789012345678900&20160516120000&025e119557284840a52ec6a404123456&POST&/v1/open&channel=PAY_CIBEPAY&order_amount=100
- 使用应用私钥,以
SM3WithSM2
算法签名上述字符串,得到的结果(Base64编码的)即为签名值; - 以KEYID_TIMESTAMP_NONCE作为用户名,5步中得到的签名值作为密码,在发送请求时,作为HTTP BASIC认证的username和password即可。
字段加密
本系统支持敏感字段数据加密功能:涉及敏感数据字段的接口,需要在开发者本地加密后,将密文传输给开放银行平台。
- 加密内容为敏感字段数据明文;
- 加密算法为:
SM4
,密码器类型为:SM4/CBC/PKCS5Padding
(算法/模式/补码方式),初始向量全部为0;
响应报文验签算法
本系统支持对请求响应报文进行签名,并将签名值随同响应报文返回。
- 签名内容为时间戳+请求随机数+报文内容;
- 签名值、请求随机数及时间戳在返回的Headers中,分别是
Signature
、Nonce
、Timestamp
; - 开发者对响应报文验签使用应用的响应报文验签公钥,以
SM3WithSM2
算法对接收的时间戳+请求随机数+报文数据进行验签操作。
回调通知验签算法
本系统已对发出的回调通知报文进行签名,开发者收到回调通知时需进行验签操作,以确保报文未被篡改。
- 签名内容为各部分以符号&拼接:应用ID&时间戳&随机值&报文内容;
- 应用ID、时间戳及随机值在返回的Headers中,分别是
Keyid
、Timestamp
、Nonce
; - 报文内容在返回的body中;
- 签名值、回调通知标识、回调通知版本号在返回的Headers中,分别是
Signature
、Callback-Type
、Version
; - 开发者将收到的回调通知报文按签名内容规则拼接后,使用应用的响应报文验签公钥,以
SM3WithSM2
算法进行验签操作。
接入
环境地址
环境类型 | URL |
---|---|
生产环境 | https://open.cibfintech.com |
错误处理
以下为本系统通用的错误信息:
注:若错误码不为OPEN前缀,则为相应服务的异常,请在所调用服务的API文档相关章节中查看。
code | 说明 |
---|---|
OPEN25001 | 验签失败 |
OPEN25002 | 请求过期 |
OPEN25003 | 未配置密钥信息 |
OPEN25004 | 超过调用频率限制 |
OPEN25005 | 随机数无效 |
OPEN25101 | 输入参数格式错误 |
OPEN25102 | 输入参数不合法 |
OPEN25201 | 没找到对应的请求资源 |
OPEN25202 | 没找到对应的开发者信息 |
OPEN25203 | 该请求无权限访问 |
OPEN25204 | 请求参数未找到 |
OPEN25205 | 没有找到对应的服务 |
OPEN25206 | 权限不足 |
OPEN25207 | 文件不存在或传输异常 |
OPEN25213 | 密钥重置失败 |
OPEN25216 | 余额不足 |
OPEN25301 | 调用后端服务出现异常 |
OPEN25303 | 后端服务返回未知异常 |
OPEN25999 | 系统繁忙,如为交易类接口,请先确认交易结果后再处理 |