跳至主要內容

集成流程

大约 5 分钟

概述

本指南带您完成 Smilepayz 的完整集成流程——从获取账户到正式上线。各地区的集成步骤相同，仅凭据和部分端点不同。

开始之前

获取账户

  • 联系业务发展：联系我们的团队获取集成账户。暂不支持自助注册。
  • 完成验证：完成商户验证，以获取凭据及各地区 API 文档访问权限。

查找地区 API 文档

各地区有独立的货币与支持的支付方式，请选择您的目标地区：

地区文档货币支付方式
巴西巴西 API 文档BRLPIX、银行转账
智利智利 API 文档CLPCASHIER_CL、银行转账
哥伦比亚哥伦比亚 API 文档COPCASHIER_CO、银行转账
印度印度 API 文档INRUPI、银行转账
印度尼西亚印度尼西亚 API 文档IDRQRIS、虚拟账户
墨西哥墨西哥 API 文档MXNSPEI、银行转账
秘鲁秘鲁 API 文档PENCASHIER_PE、银行转账
菲律宾菲律宾 API 文档PHPGCASH、银行转账
泰国泰国 API 文档THBQRPAY、银行转账
越南越南 API 文档VND电子钱包、VietQR、银行转账
埃及埃及 API 文档EGPFAWRY、银行代码代付
USDTUSDT API 文档USDTUSDT_TRC20、USDT_ERC20、USDT_BEP20

集成流程

请先在沙盒环境开发与测试——数据均为模拟，不涉及真实资金。生产环境同样遵循以下六步；差异见正式上线（生产环境）。

步骤 1：获取凭据

  1. 登录 商户后台门户open in new window。
  2. 切换到 Sandbox 选项卡。
  3. 复制以下凭据：
    • Merchant ID — 沙盒 ID 以 sandbox 前缀开头。
    • Merchant Secret — 用于签名请求；请勿修改或泄露。
    • Platform Public Key — 用于验证 Smilepayz 回调。

相关信息

沙盒凭据仅用于测试，无法在生产环境使用。

步骤 2：配置 IP 白名单与回调 URL

  • IP 白名单：在沙盒中自行配置，添加开发服务器 IP——参见沙盒 IP 配置。
  • 回调 URL：在商户后台配置，或在每次请求中传入 callbackUrl。必须使用 HTTPS。

步骤 3：生成 RSA 密钥对

  1. 在后台点击生成 RSA 密钥。
  2. 保存公钥后刷新页面，确认已成功存储。
  3. 妥善保管私钥，切勿泄露。

注意

保存的公钥必须与用于签名的私钥配对。密钥不匹配会导致签名错误。

步骤 4：集成 API

Base URL（沙盒）：https://sandbox-gateway.smilepayz.com · API 版本：v2.0 · 仅 HTTPS。

可从以下 SDK 示例入手：

语言仓库
JavaJava 演示open in new window
C#C# 演示open in new window
PHPPHP SDKopen in new window
PythonPython 演示open in new window
Node.jsNode.js 演示open in new window
GolangGolang 演示open in new window

将示例中的 merchantId、merchantSecret、privateKey 替换为您自己的凭据。密钥请存入环境变量，不要写在源码中。

步骤 5：创建订单

响应 code 为 00 表示订单创建成功。使用返回的 orderNo 跟踪订单。沙盒中的 paymentUrl 为模拟数据，无法完成真实支付。

{
  "code": "00",
  "channel": {
    "paymentUrl": "https://sandbox-gateway.smilepayz.com/cashier/#/loading?tradeNo=T1112001925061115234920979"
  },
  "orderNo": "S200192eeacf6ed4f74406900c8f1039",
  "responseCode": "2009000",
  "message": "Success"
}

在沙盒中可手动触发回调，以测试状态更新与错误处理。

步骤 6：处理回调

  1. 获取平台公钥。
  2. 验证回调签名——在处理数据前务必验证。
  3. 返回 SUCCESS 确认收到。

正式上线（生产环境） {#going-live-production}

沙盒端到端测试通过后，即可切换至生产环境。流程相同，仅以下差异：

沙盒生产环境
凭据来自 Sandbox 选项卡来自 Production 选项卡的独立凭据
Base URLhttps://sandbox-gateway.smilepayz.comhttps://gateway.smilepayz.com
IP 白名单自行配置提交给客户服务
Payment URL模拟数据真实收银台，因地区而异
资金模拟真实资金

上线步骤：

  • 获取生产凭据：在 商户后台open in new window 的 Production 选项卡中获取，与沙盒完全独立——切勿混用。
  • 提交 IP 白名单：生产环境须提交给客户服务，无法自行配置。生产回调 URL配置方式与沙盒相同。
  • 生成生产 RSA 密钥对并刷新页面确认公钥已保存。
  • 将集成指向 https://gateway.smilepayz.com，使用生产凭据。
  • 处理响应：返回的 channel 因地区而异——参见支付渠道模型。获取生产公钥以验证生产回调。

注意

生产环境处理真实资金。切勿在生产环境使用沙盒凭据。

最佳实践

  • 保护密钥：凭据不要写入源码；使用环境变量或密钥管理服务。
  • 验证每条回调：处理回调数据前务必验证签名。
  • 使用 HTTPS 与 IP 白名单：加密所有流量，并限制为授权 IP。
  • 记录与监控：记录请求、响应与回调，便于排查与审计。
  • 上线前充分测试：在沙盒中跑通完整流程后再上线。

支持

  • 文档：本站 API 参考与集成指南。
  • 技术支持：联系支持团队获取集成帮助与故障排查。
  • 业务发展：账户开通、地区接入与商务条款。
Copyright © 2026 smilepayz teams