蓝鲸支付接入教程
本教程按现有接口实现说明蓝鲸支付的后台配置、创建订单、签名、返回字段和异步通知。生产接入应在服务端完成签名与验签，并为订单更新建立幂等约束。
一、完成后台设置
登录管理后台，在“系统设置”中配置以下项目：
- 通讯密钥：创建订单和通知验签共同使用。
- 异步回调：支付确认后通知业务系统的公网地址。
- 同步回调：支付页完成后的浏览器跳转地址。
- 订单有效期：待支付订单参与匹配的分钟数。
- 区分方式：并发同金额订单采用金额递增或递减。
- 微信码/支付宝码：上传无固定金额收款二维码。
二、创建订单接口
请求地址为：
https://你的商户域名/createOrder
接口支持 GET 或 POST。建议服务端使用 POST 发起请求，避免敏感参数长时间出现在浏览器历史和前端日志中。
三、创建订单参数
| 参数 | 必填 | 说明 |
|---|---|---|
| payId | 是 | 业务系统唯一商户订单号 |
| param | 否 | 透传参数，通知时原样返回 |
| type | 是 | 1 微信，2 支付宝 |
| price | 是 | 订单金额 |
| notifyUrl | 否 | 本订单异步通知地址 |
| returnUrl | 否 | 本订单同步跳转地址 |
| sign | 是 | 创建订单签名 |
| isHtml | 否 | 0 返回 JSON，非 0 跳转支付页 |
四、创建订单签名
将字段原值按固定顺序无分隔符拼接，再计算 MD5：
sign = md5(payId + param + type + price + 通讯密钥)
param 未使用时按空字符串处理。不要先对金额做与请求值不同的格式化，也不要在客户端暴露通讯密钥。
五、创建订单返回
成功响应外层包含 code=1、msg=成功 和 data。主要业务字段包括：
payId：商户订单号。orderId：蓝鲸支付平台订单号。payType：支付方式。price：原订单金额。reallyPrice：顾客实际应付金额。payUrl：支付二维码内容。state：订单状态。timeOut：订单超时时间。
状态值：-1 已过期，0 等待支付，1 已完成，2 已支付但通知失败。
六、异步回调字段
支付确认后，系统向通知地址发送 GET 请求，字段为：
payId, param, type, price, reallyPrice, sign
若创建订单传入了 notifyUrl，优先使用该地址；否则使用后台默认异步回调。
七、回调验签
sign = md5(payId + param + type + price + reallyPrice + 通讯密钥)
- 按原始参数字符串计算签名并进行安全比较。
- 查询
payId对应业务订单。 - 校验订单状态、支付方式和金额。
- 在事务中幂等更新订单并完成发货。
- 成功后返回纯文本小写
success。
响应必须严格为
success。返回 JSON、页面内容或其他字符串会被判定为通知失败。八、联调建议
- 先使用独立测试商品和小额订单验证微信、支付宝。
- 分别测试 JSON 返回和支付页跳转模式。
- 测试空
param、自定义通知地址和订单超时。 - 重复发送同一回调，确认不会重复发货。
- 让回调临时返回错误内容，确认后台显示通知失败且可排查。