先选协议
码支付兼容易支付 V1 和 V2。老系统优先 V1,新系统建议 V2;两者都支持页面跳转和 API 下单。
| 项目 | 易支付 V1 | 易支付 V2 |
|---|---|---|
| 签名算法 | MD5 | RSA-SHA256 |
| 请求格式 | 表单 / 页面跳转 | JSON API |
| 密钥 | 商户密钥 | 商户私钥 + 平台公钥 |
| 适合 | 存量系统、现成插件 | 新系统、安全性要求高 |
| 回调验签 | MD5 验签 | RSA 验签 |
接入前准备
商户信息
在后台获取商户 ID(pid),确认套餐已开通、通道可用。
回调地址
准备公网可访问的 HTTPS 地址,能接收 GET 或 POST 回调,并返回文档要求的成功标识。
订单规则
确定商户订单号生成规则、金额单位(元/分)和幂等键,避免重复回调造成重复发货。
V1 常用参数
| 参数 | 必填 | 说明 |
|---|---|---|
| pid | 是 | 商户 ID |
| type | 是 | 支付方式,如 alipay、wxpay |
| out_trade_no | 是 | 商户订单号,需唯一 |
| notify_url | 是 | 异步回调地址 |
| return_url | 否 | 支付完成后返回地址 |
| name | 是 | 商品名称 |
| money | 是 | 订单金额,单位元 |
| sign | 是 | 签名结果 |
| sign_type | 是 | 固定为 MD5 |
V1 签名示例
待签名串:
money=1.00&name=测试商品¬ify_url=https://your.site/notify
&out_trade_no=MP202611170001&pid=10001&type=alipay
sign = MD5(待签名串 + 商户密钥)
参数按名称 ASCII 升序排列,空值不参与,sign 和 sign_type 不参与签名。具体规则以 在线文档 为准。
V2 常用参数
| 参数 | 说明 |
|---|---|
| pid | 商户 ID |
| type | 支付方式 |
| out_trade_no | 商户订单号 |
| name | 商品名称 |
| money | 订单金额 |
| notify_url | 异步回调地址 |
| return_url | 同步返回地址 |
| timestamp | 请求时间戳 |
| sign_type | 固定为 RSA |
| sign | RSA-SHA256 签名 |
回调处理
接收参数
从 GET 或 POST 中读取订单号、金额、状态和签名。
验证签名
V1 用 MD5,V2 用平台公钥验签;失败直接丢弃并记录日志。
校验订单
核对商户订单号、金额和订单状态,防止金额被篡改。
幂等处理
同一订单可能多次回调,用唯一键保证只发货一次。
常见错误
签名错误
参数排序、空值处理、密钥拼错或编码不一致都会导致验签失败。
回调收不到
地址不是公网、HTTPS 证书异常、防火墙拦截,或返回内容不符合要求。
金额不一致
元/分单位混用,或回调金额没有和本地订单比对。
完整接入流程
准备商户信息
在后台获取 pid、密钥或 RSA 密钥对,确认套餐和通道可用。
选择协议
存量系统用 V1,新系统优先 V2;确定页面跳转还是 API 下单。
创建订单
按文档拼接参数并签名,调用下单接口。
展示支付
根据返回结果展示二维码或跳转地址。
处理回调
接收 notify_url 通知,验签、核对金额、做幂等。
小流量上线
先小额测试,再逐步放量,保留日志和回滚方案。
V1 返回与订单状态
| 字段 | 说明 |
|---|---|
| code | 接口返回码,成功和失败的取值以文档为准 |
| msg | 提示信息,可用于日志和排查 |
| trade_no | 平台订单号 |
| out_trade_no | 商户订单号 |
| status | 订单状态,支付完成以回调或查单结果为准 |
V2 签名串示例
待签名串(按文档规定排序拼接):
money=1.00&name=测试商品¬ify_url=https://your.site/notify
&out_trade_no=MP202611170001&pid=10001×tamp=1763340000&type=alipay
sign = SHA256withRSA(待签名串, 商户私钥)
V2 的字段顺序、时间戳有效期和签名串格式必须严格按文档,不能自行调整。
回调参数
| 参数 | 用途 |
|---|---|
| pid | 商户 ID |
| trade_no | 平台订单号 |
| out_trade_no | 商户订单号,用于查本地订单 |
| type | 支付方式 |
| money | 订单金额,需要和本地订单比对 |
| trade_status | 支付状态,以文档定义为准 |
| sign | 签名,必须先验证 |
| sign_type | MD5 或 RSA |
错误码与排查
| 类型 | 可能原因 | 排查方向 |
|---|---|---|
| 签名错误 | 排序、空值、密钥或编码不一致 | 打印待签名串,和文档示例逐步比对 |
| 商户不存在 | pid 填错或环境不对 | 核对后台商户 ID 和接口地址 |
| 通道不可用 | 通道未启用、维护或限额 | 查看后台通道状态和公告 |
| 订单号重复 | out_trade_no 已使用 | 每次下单生成新的唯一订单号 |
| 金额错误 | 元/分单位混用 | 统一按文档要求的单位传参 |
SDK 与建站插件
WooCommerce
WordPress 商城插件,配置商户信息后可在结算页选择支付方式。
Typecho / 独角数卡
常用发卡和博客系统插件,适合虚拟商品自动发货。
自建 SDK
按易支付 V1 / V2 协议自行封装,适合已有后端服务的团队。
上线检查清单
- 回调地址公网可访问,HTTPS 证书有效。
- 验签、金额校验、订单幂等全部实现。
- 支付成功后先查单再发货,不依赖前端跳转。
- 异常订单和回调原文有日志,可按订单号检索。
- 准备备用通道和降级提示。