结论

ToneTag Payment SDK 通常不是可从公开仓库直接下载的通用 SDK。商户或支付服务商需要先向 ToneTag 申请合作接入，通过商务审核后，才能取得开发者账号、SDK 包、接口文档、测试凭据和测试环境权限。

如果官网只有产品介绍，没有 SDK 下载入口，通常说明这些资源只向通过审核的合作方开放。不要从第三方网盘或非官方仓库下载 SDK，否则可能遇到版本过期、二进制文件被篡改或支付合规问题。

获取 SDK

可以通过 ToneTag 官网提供的销售、商务合作或技术支持渠道提交接入申请。申请时通常需要准备：

• 公司名称和业务所在地
• 应用名称、业务类型及预计交易规模
• Android、iOS、Web 或服务端等目标平台
• 商户或支付机构资质
• 计划接入的收单机构、银行或支付渠道
• 技术联系人和企业邮箱
• 测试环境与正式环境的上线计划

审核通过后，需要向对方确认能否提供：

• 对应平台的 SDK 文件或私有依赖地址
• SDK 集成手册和 API 文档
• 示例工程
• Sandbox 测试账号及凭据
• 商户编号、终端编号等业务标识
• 服务端签名和验签规范
• 回调地址的配置方法
• 正式环境申请及上线验收流程

如果业务已经接入某家银行、收单机构或支付网关，也可以先向该机构咨询。ToneTag 的能力可能由合作机构间接提供。在这种情况下，应使用合作机构提供的接口和凭据，不必单独向 ToneTag 获取 SDK。

推荐的集成结构

支付流程不能完全依赖客户端 SDK。更稳妥的结构如下：

Mobile App
    │
    ├── 调用业务服务端创建订单
    │
    ▼
Merchant Backend
    │
    ├── 保存订单并生成唯一订单号
    ├── 调用支付服务创建交易
    │
    ▼
ToneTag / Payment Provider
    │
    ├── 返回客户端所需的支付参数
    ▼
Mobile App
    │
    ├── 调用官方 SDK 发起支付
    ▼
ToneTag / Payment Provider
    │
    ├── 向商户服务端发送异步通知
    ▼
Merchant Backend
    ├── 验签
    ├── 查询并核对交易状态
    └── 更新订单

客户端返回的”支付成功”只能用于界面提示，不能作为发货、充值或记账的唯一依据。最终状态应以通过验签的服务端通知或主动查询结果为准。

基本接入步骤

1. 创建服务端订单

服务端需要生成不可重复的商户订单号，并保存金额、币种、用户和订单状态。金额最好使用最小货币单位的整数表示，以免产生浮点数误差。

{
  "merchantOrderId": "ORDER_20260913_000001",
  "amount": 12500,
  "currency": "INR",
  "callbackUrl": "https://merchant.example.com/payments/tonetag/callback"
}

这些字段只用于展示常见的数据结构，不代表 ToneTag 的实际 API。字段名称、币种要求和金额单位都应以合作方提供的文档为准。

2. 由服务端创建支付交易

密钥、签名私钥和正式环境凭据必须保存在服务端，不能写入 Android APK、iOS App、JavaScript 或公开代码仓库。

// 示例为接口结构示意，不是 ToneTag 官方 API。
async function createPayment(order) {
  const payload = {
    merchantOrderId: order.id,
    amount: order.amount,
    currency: order.currency,
    callbackUrl: process.env.PAYMENT_CALLBACK_URL
  };

  const signature = signPayload(
    payload,
    process.env.PAYMENT_PRIVATE_KEY
  );

  return paymentProvider.createTransaction(payload, signature);
}

服务端应保存支付平台返回的交易标识和客户端参数，再将可以公开的部分返回给应用。

3. 在客户端引入 SDK

SDK 的安装方式由官方交付形式决定。例如，Android 可能通过私有 Maven 仓库或 .aar 文件提供，iOS 可能通过 CocoaPods、Swift Package Manager 或 .xcframework 提供。

以下配置只展示一种常见形式，不能直接作为真实的依赖配置使用：

dependencies {
    implementation(files("libs/vendor-payment-sdk.aar"))
}

不要自行猜测 Maven 坐标、包名或 SDK 初始化类。依赖名称和校验值必须以官方文档为准，同时还要确认 SDK 是否要求特定的 minSdk、权限、混淆规则或硬件能力。

4. 调用 SDK 发起支付

客户端应使用服务端返回的短期支付令牌或交易参数调用 SDK，不要在本地生成签名。

// 伪代码：类名和参数不代表 ToneTag 的实际接口。
fun startPayment(paymentToken: String) {
    VendorPaymentSdk.startPayment(
        context = this,
        paymentToken = paymentToken,
        callback = object : PaymentCallback {
            override fun onSuccess(transactionId: String) {
                queryOrderStatusFromMerchantServer()
            }

            override fun onFailure(code: String, message: String) {
                showPaymentFailure(message)
            }

            override fun onCancelled() {
                showPaymentCancelled()
            }
        }
    )
}

即使收到 onSuccess，客户端仍应向自己的服务端查询订单状态。SDK 回调只能说明客户端流程已经结束，不一定表示服务端已确认到账。

5. 处理异步通知

回调接口必须验证签名，核对订单号和金额，并确保重复通知不会造成重复入账。

// 示例为通用处理逻辑，签名算法和请求头名称以官方文档为准。
app.post("/payments/tonetag/callback", async (req, res) => {
  const signature = req.headers["x-payment-signature"];

  if (!verifySignature(req.rawBody, signature, process.env.PAYMENT_PUBLIC_KEY)) {
    return res.status(401).send("invalid signature");
  }

  const event = req.body;
  const order = await findOrder(event.merchantOrderId);

  if (!order) {
    return res.status(404).send("order not found");
  }

  if (order.amount !== event.amount || order.currency !== event.currency) {
    return res.status(400).send("order mismatch");
  }

  if (event.status === "SUCCESS" && order.status !== "PAID") {
    await markOrderAsPaidAtomically(order.id, event.transactionId);
  }

  return res.status(200).send("OK");
});

其中的 x-payment-signature、状态值和字段名称都是通用示例。实际验签必须严格遵循官方要求，包括原始请求体、字符编码、字段顺序、时间戳和证书轮换规则。

联调时需要覆盖的场景

联调时至少要验证：

• 支付成功、失败和用户取消
• 支付处于处理中，稍后才收到最终结果
• SDK 返回成功，但异步通知延迟
• 客户端断网、退出或被系统杀死
• 同一订单被重复提交
• 回调被重复发送或乱序到达
• 金额、币种或商户订单号不匹配
• 签名错误、时间戳过期或凭据失效
• Sandbox 与正式环境配置混用
• 退款、撤销和交易查询

订单更新必须具备幂等性。同一笔交易的通知即使多次到达，也只能完成一次记账或发货。

注意事项

ToneTag 的方案可能涉及音频或设备能力。在某些集成模式下，应用可能需要麦克风权限、音频会话配置或设备兼容性测试，但不能只根据产品名称提前添加权限。应先查阅实际取得的 SDK 官方说明。确认需要麦克风权限后，还要提供清晰的用途说明，并遵守 Android、iOS 和当地隐私法规的要求。

还需要注意：

• 彻底隔离测试环境与正式环境的地址、证书和凭据。
• 不要记录完整的支付令牌、密钥或敏感用户信息。
• 使用 HTTPS，并验证服务端证书。
• 核实 SDK 文件的来源、版本和哈希值。
• Android 发布前确认 R8/ProGuard 规则，iOS 发布前确认签名和架构支持。
• 明确交易查询、超时、退款和对账机制。
• 在拿到书面接口文档之前，不要根据网上的零散示例实现生产支付流程。

当前应先完成 ToneTag 官方或合作收单机构的接入申请，而不是直接编写 SDK 调用代码。取得明确的 SDK 平台、版本和接口文档后，才能确定可执行的依赖配置、初始化代码和支付调用方式。

备注：内容仅供参考。