接入指引
通讯协议
请求和响应数据使用明文传输,请求和响应头存在数据签名,签名的生成规则为JSON
数据的键排序后值使用&
拼接然后使用RSA
签名。
平台请求报文上送时,需要指定请求类型为JSON
,请求数据为JSON
类型的明文数据,同时将数据按照规则生成签名,请求头中指定APPID
和接口版本,接口返回响应结果时,响应内容为JSON
,响应头中包含响应结果签名。
*加密加签处理由SDK
请求内部完成。
加密流程:
公用请求响应头设置
所有API
接口的请求头,用来标明接口版本,编码和商户的基本信息等公用参数:
参数名称 | 参数含义 | 类型 | 长度 | 必填 | 参数说明 | 示例值 |
---|---|---|---|---|---|---|
x-yeeverse-appid | 应用ID | String | Max(32) | 是 | APP_3001000 | |
x-yeeverse-sign | 请求数据签名 | String | Max(2048) | 是 | ||
x-yeeverse-sdk-version | 接口版本 | String | Max(32) | 是 | V4 | |
Content-Type | 请求类型 | String | Max(64) | 是 | application/json; charset=utf-8 |
所有API
接口的响应头,用来标明接口版本,编码和商户的基本信息等公用参数:
参数名称 | 参数含义 | 类型 | 长度 | 必填 | 参数说明 | 示例值 |
---|---|---|---|---|---|---|
x-yeeverse-response-id | traceid | String | Max(64) | 是 | 查询问题的时候提供给技术,方便快速定位问题 | 3185486268694 |
x-yeeverse-sign | 响应数据签名 | String | Max(2048) | 是 |
加密说明
ISV 机构服务商需先准备RSA
公私钥对(位数2048,密钥格式PKCS#8
,输出格式Base64
),将公钥在 ISV 的商户后台《开发配置》进行配置,支付平台进行验证通过后即可使用,同时支付平台提供测试账号和平台公钥,平台公钥用于解密平台返回数据使用。
数据处理过程:
请求参数:中文编码为
UTF-8
,类型为JSON
,需要对请求参数签名然后放在请求头中请求成功后,响应体中返回响应结果,类型为
JSON
,同时响应头中包含对请求体的签名,需要对签名请求响应签名串拼接方法(获取所有的
JSON
键值排序后签名)
// 拼接加密传原文
StringBuilder rowData = new StringBuilder();
for (String key : keyList) {
Object value = dataMap.get(key);
if (Objects.nonNull(value)) {
rowData.append(value);
rowData.append(SdkConstants.STRING_SEPARATER);
}
}
- 加解密工具类,采用标准
RSA
SHA256withRSA
签名算法进行数据签名
// 获取私钥
$privateKey = RSAUtils::GetPrivateKey($privateKeyStr);
// 将私钥导入openssl资源
$privateKey = openssl_get_privatekey($privateKey);
// 使用SHA256算法对资源进行签名
$res = openssl_sign($resource, $signature, $privateKey, OPENSSL_ALGO_SHA256);
// 释放私钥资源
openssl_free_key($privateKey);
// 如果签名成功,则返回Base64编码的签名字符串
if ($res) {
return base64_encode($signature);
} else {
// 如果签名失败,则抛出异常
error_log("String Sign Failed");
throw new \Exception("String Sign Failed", 10004);
}
*注意:商户需要在商户后台配置商户公钥,或线下提交支付平台。
异步通知
通知方式: 将参数通知到请求时传入的serverCallbackUrl
。
通知机制: 异步通知一次,如通知失败,之后会进行补偿通知,每5分钟通知1次,最多再通知9次。
接收机制: 接收回调通知的key
为notify
,返回数据为JSON
串,需要对其中的response
字段进行解析。
应答方式: 状态码:200;响应报文:SUCCESS
异常情况:
①对接平台未收到通知的情况有:
1.商户系统拦截了支付平台的异步通知;
2.订单一直处于担保中未确认的情况。这两种情况均建议商户系统在超过订单有效期之后还未收到通知,应先调用支付查询接口,以确认订单状态,来更新本地订单状态。
②对接平台接收到异步通知,但本地订单已通过查询补偿更新为成功的时候,需做幂等操作,以免重复接收异步通知。
SDK
下载地址
JAVA
版本:https://gitee.com/yeeverse-api-sdk_1/api-sdk-javaPHP
版本:https://gitee.com/yeeverse-api-sdk_1/api-php-sdk
生产配置
(*短剧宝对接请查看《短剧宝API配置指南》专区)
待测试联调完成后,联系易链星云对接销售人员进行入网配置,入网完成后,下发对应后台商户登录账号后,即可进行生产数据参数配置
*注意:短剧宝API 需要通过《三、生成RSA密钥》生成对应公私钥后,将公钥提供给对应的运营或技术支持人员进行配置.
1、登陆NaaS
后台:
正式环境: https://yvmerchant.yeepay.com/zfzx/index.html#/visitor/login
账号: 商户yeeverse
商编+admin
初始密码: 请点击【忘记密码】重新配置密码。
2、登陆账号后,点击【通道管理】—【开发配置】
3、生成RSA
密钥
商户通过地址 https://open.yeepay.com/docs/open/platform-doc/developTools-sm/keyTools-sm 下载密钥生成器,生成RSA
公私钥。
注:私钥需要商户自己保存。