准备工作
开始前先联系官方客服开通接入应用,拿到下面三样。三个系统用的都是这同一组参数。
| 参数 | 说明 |
|---|---|
| 网关域名 | 客服提供的支付网关,如 https://网关域名 |
商户 ID(pid) | 接入应用的商户 ID |
商户密钥(key) | 接入应用的密钥,用于 MD5 签名,不要外泄 |
旧版独角数卡的官方仓库已在 2026 年 2 月停止维护,并建议迁移到新版 Dujiao-Next。两版的配置方式不一样,请按你实际在用的版本看对应章节。
旧版独角数卡(2.x)
登录后台,打开「支付通道」。系统默认已经预置了「易支付-支付宝」「易支付-微信」「易支付-QQ 钱包」三条,编辑你要用的那条即可;如果被删掉了就新增一条。
| 后台字段 | 填什么 |
|---|---|
| 支付名称 | 展示给买家的名字,如「支付宝」 |
| 商户 ID | pid |
| 商户 KEY | 完整的下单地址:https://网关域名/submit.php |
| 商户密钥 | key |
| 支付标识 | alipay(支付宝)或 wxpay(微信) |
| 支付方式 | 跳转 |
| 支付场景 | 通用 |
| 支付处理路由 | /pay/yipay |
| 是否启用 | 开启 |
最容易填错的是「商户 KEY」:独角数卡把这一栏原样当作跳转地址来用,所以这里要填带 /submit.php 的完整地址,而密钥要填在「商户密钥」里。两栏填反会直接验签失败或跳转 404。
支付宝和微信各用一条通道,两条的商户 ID、下单地址、密钥都相同,只有「支付标识」不同。
异步通知地址由程序自动生成,是 https://你的域名/pay/yipay/notify_url,不需要手填,只要保证这个地址能被公网访问。
新版 Dujiao-Next
- 后台打开「支付渠道」,点新增。
- 「渠道类型」选「易支付」,「支付方式」选「支付宝」或「微信」。
- 「交互方式」选「跳转」(页面跳转,走
/submit.php)或「二维码」(API 下单,走/mapi.php)。 - 在「易支付配置」里先把「版本」改成
v1,再按下表填写并保存。
| 易支付配置 | 填什么 |
|---|---|
| 版本 | v1(默认是 v2,必须改) |
| 支付网关 | https://网关域名/ |
| 商户ID | pid |
| 商户密钥 | key |
| 通知地址 | https://你的域名/api/v1/payments/callback |
| 同步地址 | https://你的域名/pay |
版本一定要选 v1。v2 用的是 RSA 密钥对,和泡泡支付提供的 MD5 密钥不通用,选错会验签失败。
「交互方式」选「二维码」时,Dujiao-Next 会从你的服务器直接请求 /mapi.php,需要先把服务器的公网出口 IP 提供给官方客服加入白名单;选「跳转」则不需要。
支付宝和微信各建一个渠道,配置相同,只有「支付方式」不同。
下单测试
- 在前台上架一个低价的测试商品。
- 用刚配置的支付方式下单,页面应跳到收银台或显示付款二维码。
- 完成支付后回到订单页,订单变成已支付并自动发货,说明配置成功。
如果钱付了但订单一直是待支付,说明异步通知没有送达或没通过验签,请看下一节。
常见问题
| 现象 | 原因与处理 |
|---|---|
| 跳转后提示「验签失败」 | 密钥填错位置或带了空格。旧版确认 key 填在「商户密钥」而不是「商户 KEY」;新版确认「版本」是 v1 |
| 跳转后 404 或页面打不开 | 旧版的「商户 KEY」没有带 /submit.php,或网关域名写错 |
| 接入应用未配置支付方式 xxx 对应的产品 | 这个支付方式还没开通,或支付方式编码写错了(微信是 wxpay,不是 wechat)。编码无误就联系官方客服配置 |
| 支付成功但订单仍是待支付 | 异步通知没到。确认通知地址能被公网访问、没有被防火墙或 CDN 拦截;新版再确认「通知地址」填的是 /api/v1/payments/callback。排查后可联系客服补发通知 |
| 非法请求,请添加接口IP白名单 | 新版用了「二维码」交互方式但服务器 IP 不在白名单。把公网出口 IP 提供给客服,或改用「跳转」 |
其他对接文档
获取商户 ID 与密钥
联系官方客服开通接入应用,网关地址、pid 与 key 由客服直接提供,专人协助联调。
联系官方客服