Android 与 iOS 原生 SDK

以 Android 原生 View 或 iOS SwiftUI 直接嵌入 PolyPay 支付方式选择页和付款页，不使用收银台 WebView。

原生收银台流程

App 请求已认证的商户服务端创建 checkout；服务端不传 currency 和 network，只返回 checkout_url。
SDK 校验 HTTPS 域名，并从 /pay/{tradeId} 提取不透明交易 ID。
原生支付方式页加载商户可用币种、网络和预估网络费。
用户选择后，Android 对兼容 EVM 付款直接调起钱包，其余情况展示精确手动付款信息；iOS 当前保留地址二维码和复制流程。
商户服务端仅在 webhook 验签成功或认证对账查询确认后履约。

1. 在服务端创建可选支付方式的 checkout

X-API-Key 必须只保存在服务端。创建时不传 currency 和 network，使订单进入“等待选择支付方式”状态。

// Trusted merchant server only. Never return the API Key to the app.
const response = await fetch('https://api.polypay.ai/api/v1/pay/order/checkout', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.POLYPAY_API_KEY!
  },
  body: JSON.stringify({
    mch_order_id: order.id,
    amount: order.amount,
    notify_url: 'https://merchant.example.com/webhooks/polypay'
    // Omit currency and network: the native SDK shows the selector.
  })
});

return { checkoutUrl: (await response.json()).data.checkout_url };

2. 安装原生 SDK

Android（Kotlin）

dependencies {
  implementation("ai.polypay:checkout:0.1.1")
}

private val checkout = registerForActivityResult(PolyPayCheckoutContract()) { result ->
  // PAYMENT_DETECTED is not a fulfillment decision.
  viewModel.reconcileOnMerchantServer(result.tradeId)
}

checkout.launch(
  PolyPayCheckoutOptions(checkoutUrl = checkoutUrlFromYourServer)
)

iOS（SwiftUI 或 UIKit）

添加 Swift Package，创建经过校验的配置，再展示 SwiftUI View 或 UIKit hosting controller。支持 iOS 15 及以上。

https://github.com/PolyPayAi/ios-sdk.git

let configuration = try PolyPayCheckoutConfiguration(
  checkoutURL: checkoutURLFromYourServer
)

PolyPayCheckoutView(configuration: configuration) { outcome in
  // paymentDetected is not a fulfillment decision.
  merchantAPI.reconcile(outcome)
}

SDK 内置原生页面

支付方式页	币种选项、兼容网络、商户默认项以及服务端提供的预估网络费。
付款页	精确金额、币种、网络、收款地址、复制操作、Android EVM 钱包调起和实时观察状态。
终态页面	确认中、已检测、已过期、已取消、可重试网络错误与安全关闭。

SDK 返回结果与履约权威

SDK 返回值刻意不包含 paid。Android 的 PAYMENT_DETECTED 和 iOS 的 paymentDetected 只表示公开订单状态发生变化；App 必须把 trade ID 交给商户服务端对账后才能履约。

安全要求

API Key、checkout 签名密钥、webhook 密钥和结算凭据不得进入 App。
只接受精确域名白名单中的 HTTPS /pay/{tradeId} URL。
金额、地址、网络和手续费报价均使用服务端返回值，App 不自行计算收款目标。
最终订单状态只认 Webhook v2 验签结果或服务端认证查询。
更换支付方式时由服务端取消旧的未付款尝试，绝不覆盖已验证的付款状态。

发布验证

构建 Android Release AAR、示例 APK，并执行单元测试和 Lint。
在 macOS 执行 Swift 测试并构建 iOS Simulator 包。
真机验证 Android 钱包调起与手动复制、iOS 二维码扫描，以及过期、取消、确认和关闭。
检查安装包和日志，证明其中没有商户密钥。
验证任何客户端事件都不会绕过服务端对账直接履约。