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）

註冊 Activity Result contract，再傳入服務端返回的 checkout URL。支援 Android API 24 及以上。

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 二維碼掃描，以及過期、取消、確認和關閉。
檢查安裝包和日誌，證明其中沒有商戶金鑰。
驗證任何客戶端事件都不會繞過服務端對帳直接履約。