接口规范

注意事项

  • 系统返回的应答或通知消息可能会由于升级增加参数,请验证通知签名或处理应答报文时注意允许这种情况。
  • 应用密钥需要严格保密。如因开发者的应用密钥泄露而导致的安全问题,损失需要由开发者自行承担。
  • 所有接口报文统一使用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中,分别是SignatureNonceTimestamp
  • 开发者对响应报文验签使用应用的响应报文验签公钥,以SM3WithSM2算法对接收的时间戳+请求随机数+报文数据进行验签操作。

回调通知验签算法

本系统已对发出的回调通知报文进行签名,开发者收到回调通知时需进行验签操作,以确保报文未被篡改。

  • 签名内容为各部分以符号&拼接:应用ID&时间戳&随机值&报文内容
  • 应用ID、时间戳及随机值在返回的Headers中,分别是KeyidTimestampNonce
  • 报文内容在返回的body中;
  • 签名值、回调通知标识、回调通知版本号在返回的Headers中,分别是SignatureCallback-TypeVersion
  • 开发者将收到的回调通知报文按签名内容规则拼接后,使用应用的响应报文验签公钥,以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 系统繁忙,如为交易类接口,请先确认交易结果后再处理
© CIB FINTECH CO.,LTD All Rights Reserved.Last Update: 2020-11-05

results matching ""

    No results matching ""