码支付接入指南 · 个人商户开通流程账号配置接口联调上线注意事项

码支付接入指南详细讲解个人开发者及企业商户从注册开通账号、收款通道绑定、 接口参数配置、沙箱测试环境联调、回调地址部署设置到正式环境上线的完整流程步骤， 并附常见对接问题排查方案，助您零障碍完成支付接入。

01

账号注册与实名开通

预计耗时 3 分钟
  1. 访问码支付官网点击右上角「免费注册」，输入手机号码与图形验证码完成账号创建。
  2. 登录控制台后进入「账户设置 - 实名认证」，填写身份证信息并完成人脸或银行卡四要素核验。
  3. 实名通过后自动升级为正式商户，系统赠送首月 10 万流水免服务费体验额度。
  4. 进入「应用管理」创建第一个接入应用，记录分配的 AppID 与 AppSecret 密钥。
⚠️

AppSecret 是接口调用的核心密钥，仅在创建时显示一次，请妥善保存在服务器环境变量中，不要提交到公开代码仓库。泄露密钥可能导致订单被恶意篡改造成资金损失。

02

收款通道与账号绑定

预计耗时 10 分钟
  1. 进入「通道配置 - 微信扫码」页面，使用管理员微信号扫码绑定收款账户，完成授权确认。
  2. 切换到「支付宝当面付」Tab，使用绑定的支付宝账号扫码登录授权开通收款权限。
  3. 在「收款设置」中配置每日收款上限与单笔金额阈值，超限时自动切换备用通道。
  4. 建议绑定 2-3 个同类型备用收款号，并开启「智能分流」功能分散单账号收款压力。
03

接口参数与回调地址配置

预计耗时 15 分钟
配置项 填写要求与说明
异步回调地址 notify_url 必须为外网可直接访问的 POST 接口 URL，不支持内网、localhost、带端口号的测试地址。建议路径：/api/mapay/notify.php，服务器需允许码支付平台出口 IP 段访问。
同步跳转地址 return_url 用户在电脑端完成支付后自动跳回的页面地址，仅用于展示支付结果给用户，业务逻辑不能依赖此地址执行，必须以异步回调为准。
IP 白名单 在「安全设置 - IP白名单」中填写您的服务器出口公网 IP 地址列表，列表外服务器的 API 请求将被自动拒绝。支持单个 IP 或 CIDR 段格式。
签名算法类型 推荐使用 HMAC-SHA256 以获得更高的防碰撞安全性，MD5 仅作为兼容旧版本保留。修改后需同步更新 SDK 初始化配置。
04

沙箱环境与联调测试

预计耗时 30 分钟
🛠 沙箱环境接入要点
  • 将 SDK 初始化的 gateway 参数切换为沙箱地址：https://sandbox.mapay.example.com/v1/
  • 沙箱环境使用独立的 AppID，可在「开发者工具 - 沙箱控制台」申请获取。
  • 沙箱金额单位与正式一致（分），支持模拟支付成功 / 用户超时 / 付款失败三种结果。
  • 沙箱模拟支付会返回固定的测试二维码，扫码后可在沙箱控制台手动触发支付成功模拟回调。
  • 使用控制台「在线调试」工具可视化构造请求，实时查看签名计算过程与响应报文。
✅ 联调必测检查清单
  • ✓ 同金额重复下单时商户订单号不重复
  • ✓ 订单金额在客户端与服务端双重校验一致
  • ✓ 回调验签未通过时正确返回非 success 且不执行业务
  • ✓ 同一订单多次回调幂等处理，未重复发货/充值
  • ✓ 订单查询接口作为兜底轮询回调未到达场景
  • ✓ 支付超时关闭后用户补付款不会错误触发业务
  • ✓ 后台手动补单按钮能正确触发补发逻辑
  • ✓ 手机 H5 支付、微信内 JSAPI、电脑扫码三端都走通
05

正式环境上线与灰度

建议分阶段上线

完成沙箱环境全链路验证后，建议按照「10%灰度 → 50%放量 → 全量切流」三阶段策略平稳上线， 每阶段至少运行 2 小时并观察成功率、回调时延、异常订单数等核心指标。

阶段一：10% 灰度（≥2小时）
  • 上线支付开关开启灰度比例 10%
  • 关注核心支付成功率是否 ≥99.9%
  • 监控回调平均时延是否在 200ms 以内
  • 客服渠道跟进是否有用户反馈支付问题
阶段二：50% 放量（≥4小时）
  • 逐步调高灰度比例至 50%
  • 观察在高并发下通道负载是否均衡
  • 核对财务对账订单数据无差异
  • 对系统资源（CPU/内存/DB）做压力评估
阶段三：全量切换上线
  • 将旧支付通道调整为备用降级链路
  • 保留一键开关回滚能力以防万一
  • 连续观察 24 小时运行数据稳定
  • 通知客服团队完成上线确认
TROUBLESHOOT 排错速查

接入常见问题排查速查表

对接过程中 90% 的问题都能通过下方清单快速定位，建议先按顺序检查再联系技术支持。

错误码 1002

返回「签名错误 sign invalid」

  1. 确认使用的 AppSecret 与创建应用时显示的完全一致，没有首尾空格；
  2. 检查参与签名的字段是否按文档说明，包含所有必填项且剔除了 sign 字段本身；
  3. 排序必须是标准 ASCII 字典序（ksort），部分语言默认按添加顺序排序会导致问题；
  4. URL 编码参数使用 RFC 3986 标准，空格编码为 %20 而非 +；
  5. 特殊字符如中文、@、& 等传输中若被二次编码，请确认签名字符串保持原始值。
回调异常

用户已付款但业务系统未执行发货

  1. 先在码支付控制台「交易流水」查看该订单是否存在「已推送」标记，确认是否已发送回调；
  2. 如显示推送失败，查看回调失败返回的 HTTP 状态码（404/500/403）对应检查回调地址是否能公网访问；
  3. 如返回状态 200 但回调内容不是 success，查看回调接口执行逻辑是否有异常提前返回；
  4. 检查防火墙/CDN/WAF 是否拦截了平台服务器 IP 的 POST 请求，建议放行出口 IP 段；
  5. 建议在回调接口最开始就记录完整原始 POST 日志，排查时可精准复现请求数据。
错误码 1006

提示「通道维护或不可用」

  1. 进入「通道状态」页面查看当前通道实时状态，是否被系统风控判定为限流或异常；
  2. 检查对应收款账号今日收款总额是否超过账号本身或平台设定的日限额；
  3. 确认绑定的微信/支付宝是否有官方风控限制（如新账号、异地登录限制）；
  4. 使用备用通道功能切换到其他收款账号，将异常账号挂起次日自动恢复；
  5. 如持续超过 2 小时不可用请联系技术支持协助诊断具体风险原因。
订单异常

H5/JSAPI 手机支付提示域名不合法

  1. 微信 JSAPI 支付需要在商户平台配置授权支付目录，需精确到发起支付页面的路径目录；
  2. 测试环境请勿使用 localhost 或 IP 地址，必须使用备案过的二级域名正式地址；
  3. 公众号支付需要用户在微信内打开网页，并提前获取用户 openid 传给下单接口；
  4. 支付宝 H5 支付需要在开放平台配置应用域名并上传校验文件完成域名归属验证；
  5. iOS 系统下 Safari 默认禁用第三方 Cookie，跨域跳转支付请使用 URL 参数传递会话。