集成信息
大约 4 分钟
集成信息指南
在调用 Smilepayz API 之前，需在商户后台获取凭据并完成集成配置。沙盒与生产环境使用不同的凭据与设置，请先在沙盒完成开发与测试。
概述
集成需要四类信息：
| 项目 | 获取位置 | 用途 |
|---|---|---|
| Merchant ID（商户 ID） | Configuration Info 标签 | X-PARTNER-ID 请求头 |
| Merchant Secret（商户密钥） | Configuration Info 标签 | API 请求 stringToSign |
| Platform Public Key（平台公钥） | Configuration Info 标签 | 校验回调签名 |
| 商户 RSA 密钥对 | API Setting 标签 | 签名 API 请求；将公钥上传至 Smilepayz |
前提条件
- 已开通并可登录商户后台
- 调用 API 的服务器公网 IP（用于 IP 白名单）
- 代收、提现回调 URL（建议使用 HTTPS）
- 安全存放 Merchant Secret 与 RSA 私钥 的环境
沙盒环境配置
步骤 1：进入沙盒 Configuration
- 登录商户后台。
- 将顶部开关切换为 Sandbox（沙盒）。
- 在左侧菜单打开 Configuration（配置）。
页面顶部有接入步骤指引，下方有三个标签页。
步骤 2：复制 API Configuration Keys
打开 Configuration Info 标签，复制并妥善保存：
- Merchant ID — 沙盒 ID 带前缀（如
sandbox-20020） - Merchant Name
- Merchant Secret — 用于构造 API 签名
- Platform Public Key — 用于验证 Smilepayz 回调签名
可点击各字段旁的复制图标。
步骤 3：配置 API Setting
打开 API Setting 标签，完成以下三个区块后点击 Save。
API IP White List（IP 白名单）
- 填写调用 Smilepayz API 的服务器公网 IP。
- 多个 IP 用英文逗号分隔（如
192.168.1.1, 192.168.1.2）。 - 输入后按 Enter 添加为标签。
未加白名单将无法调 API
服务器 IP 未加入白名单时，沙盒/生产 API 会返回非白名单错误。
API Notify Address（通知地址）
- Payin — 代收订单完成后的回调 URL
- Withdraw — 提现完成后的回调 URL
建议使用 443 端口的 HTTPS。处理与重试说明见回调通知。
Merchant Public Key（商户公钥）
- 点击 Generate RSA Keys — 浏览器会下载密钥对文件，公钥自动填入文本框。
- 将下载的私钥安全保存在服务器侧。
- 点击 Save 将公钥注册到 Smilepayz。
详细步骤：RSA 密钥生成指南。
步骤 4：测试签名（可选）
使用 Signature Test 标签在正式调 API 前验证签名。完整签名规则见签名授权。
生产环境配置
生产环境与沙盒页面结构相同，但入口与凭据不同。
步骤 1：进入生产 Configuration
- 登录商户后台。
- 确认顶部开关为 Production（生产）。
- 进入 Settings → Configuration。
步骤 2：复制生产凭据
在 Configuration Info 中复制：
- Merchant ID（生产格式，无
sandbox-前缀） - Merchant Name
- Merchant Secret
- Platform Public Key
环境隔离
请勿在生产环境复用沙盒的密钥、RSA 密钥对或回调 URL。
步骤 3：配置生产 API Setting
在 API Setting 中配置与沙盒相同的三块内容：
- API IP White List — 生产服务器出口 IP
- API Notify Address — 生产代收、提现回调 URL（使用 HTTPS）
- Merchant Public Key — 生成或粘贴生产密钥对后点击 Save
修改后务必保存
更新 IP 白名单、通知地址或商户公钥后，请在 API Setting 点击 Save。
配置清单
沙盒
生产
故障排查
| 问题 | 处理建议 |
|---|---|
API 报 Merchant non-whitelist | 将服务器出口 IP 加入 API IP White List 并保存 |
| API 签名校验失败 | 核对 Merchant Secret、minify 后的 body、商户私钥 |
| 回调验签失败 | 使用与当前环境一致的 Platform Public Key |
| 找不到 Configuration 菜单 | 沙盒用左侧 Configuration；生产用 Settings → Configuration |