文档概述
本文档详细说明银盛扫码支付接口的技术规范,包括接口地址、请求参数、签名规则、响应格式等内容。商户可根据本文档完成扫码支付功能的对接开发。银盛扫码支付接口支持微信扫码、支付宝扫码、银联扫码等多种支付方式,适用于线下门店、自助设备、PC端网页等多种场景。
接口说明
接口基本信息
| 接口名称 | 扫码支付接口 |
|---|---|
| 接口地址 | https://api.yinshengpay.com/gateway/scanpay |
| 请求方式 | POST |
| 数据格式 | application/json |
| 字符编码 | UTF-8 |
公共请求参数
所有接口请求都需要包含以下公共参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| merchantId | String(32) | 是 | 商户号,由银盛支付分配 |
| version | String(8) | 是 | 接口版本号,当前版本:1.0 |
| timestamp | Long | 是 | 时间戳,毫秒级(13位) |
| nonceStr | String(32) | 是 | 随机字符串,长度不超过32位 |
| sign | String(64) | 是 | 签名值,详见签名规则 |
| signType | String(8) | 是 | 签名类型:MD5 或 RSA |
扫码支付接口
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orderId | String(64) | 是 | 商户订单号,唯一标识,建议格式:日期+序号 |
| amount | String(16) | 是 | 支付金额,单位:元,精确到分,如:100.00 |
| subject | String(128) | 是 | 商品名称 |
| body | String(256) | 否 | 商品描述 |
| payType | String(16) | 是 | 支付方式:WECHAT(微信)、ALIPAY(支付宝)、UNIONPAY(银联) |
| notifyUrl | String(256) | 是 | 异步通知地址,支付结果将通过此地址通知商户 |
| expireTime | Integer | 否 | 二维码有效期,单位:秒,默认300秒 |
| attach | String(256) | 否 | 附加数据,在异步通知时原样返回 |
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | String(8) | 响应码,0000表示成功 |
| msg | String(128) | 响应信息 |
| orderId | String(64) | 商户订单号 |
| qrCode | String(512) | 二维码链接,商户可将其生成二维码图片 |
| expireTime | Long | 二维码过期时间戳 |
签名规则
MD5签名
签名生成步骤:
1. 将所有非空参数按参数名ASCII码从小到大排序
2. 使用URL键值对格式拼接成字符串stringA
格式:key1=value1&key2=value2&key3=value3
3. 在stringA最后拼接API密钥
stringSignTemp = stringA + "&key=" + apiKey
4. 对stringSignTemp进行MD5加密
5. 将加密结果转换为大写
示例代码(Java):
public static String generateSign(Map<String, String> params, String apiKey) {
List<String> keys = new ArrayList<>(params.keySet());
Collections.sort(keys);
StringBuilder sb = new StringBuilder();
for (String key : keys) {
String value = params.get(key);
if (value != null && !value.isEmpty() && !key.equals("sign")) {
sb.append(key).append("=").append(value).append("&");
}
}
sb.append("key=").append(apiKey);
return MD5(sb.toString()).toUpperCase();
}
RSA签名
RSA签名步骤:
1. 将所有非空参数按参数名ASCII码从小到大排序
2. 使用URL键值对格式拼接成字符串stringA
3. 使用商户私钥对stringA进行SHA256withRSA签名
4. 将签名结果进行Base64编码
示例代码(Java):
public static String rsaSign(String data, PrivateKey privateKey) throws Exception {
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);
signature.update(data.getBytes("UTF-8"));
return Base64.getEncoder().encodeToString(signature.sign());
}
异步通知
支付完成后,银盛支付会向商户配置的notifyUrl发送异步通知。商户需要正确处理通知并返回success。
通知参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| orderId | String | 商户订单号 |
| transactionId | String | 银盛交易号 |
| amount | String | 支付金额 |
| payTime | String | 支付完成时间,格式:yyyy-MM-dd HH:mm:ss |
| payType | String | 支付方式 |
| status | String | 支付状态:SUCCESS/FAIL |
| attach | String | 附加数据 |
| sign | String | 签名 |
⚠️ 注意事项:
- 商户收到通知后,务必验证签名,确保通知来自银盛支付
- 商户需要在5秒内返回字符串"success",否则银盛会重复通知
- 银盛最多重试5次,间隔时间:15s/15s/30s/3min/10min
- 对于同一订单的重复通知,商户需要做幂等处理
错误码说明
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| 0000 | 请求成功 | - |
| 1001 | 参数错误 | 检查请求参数是否正确 |
| 1002 | 签名验证失败 | 检查签名生成规则和API密钥 |
| 1003 | 商户不存在 | 检查商户号是否正确 |
| 1004 | 订单已存在 | 更换订单号重新下单 |
| 1005 | 商户状态异常 | 联系客服处理 |
| 2001 | 支付超时 | 用户未在有效期内完成支付 |
| 2002 | 支付失败 | 用户支付失败,可重新下单 |
SDK下载
银盛支付提供多种语言SDK,简化开发工作:
- Java SDK:适用于Java后端项目
- PHP SDK:适用于PHP后端项目
- .NET SDK:适用于.NET项目
- Python SDK:适用于Python项目
SDK下载地址请登录银盛支付商户后台获取,或联系粤收付客服获取最新版本。