接口规范

注意事项

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

接入

环境地址

错误处理

以下为本系统通用的错误信息：

注：若错误码不为OPEN前缀，则为相应服务的异常，请在所调用服务的API文档相关章节中查看。