收银台

收银台适合想降低前端集成成本的场景：你的后端创建收银台会话，然后把用户跳转到 StableOps 托管支付页；支付页展示链、资产、收款地址和订单状态。这样商户侧只需要处理 创建会话 和 接收 webhook，不用自己拼支付 UI。

使用方式

1. 后端创建收银台会话：在你的服务端用 API key 调用 stableops.checkoutSessions.create，传入商户订单号、金额、可接受资产、展示标题、成功返回地址、取消返回地址，以及可选的 WalletConnect project ID。
2. 把用户跳转到收银台：创建成功后使用响应里的 checkout.url 做 303 跳转，或把 URL 返回给前端再 window.location.assign(checkout.url)。
3. 用户在收银台付款：托管页面展示链、资产、准确金额和收款地址，并实时跟踪状态。用户可以通过浏览器钱包、手机钱包或手动转账支付（详见下方支持的钱包方式）。两种方式 scanner 都按收款地址匹配入金。
4. 用 Webhook 完成业务动作：你的后端接收并验签 payment.confirmed / payment.finalized 等 Webhook 事件，再开通服务、入账或更新订单状态。不要只依赖用户跳回 successUrl，它只是前端体验，不是最终支付凭证。

你可以通过在收银台 URL 上添加 lang 参数控制页面语言，例如 ?client_secret=...&lang=es。支持的值包括 en、zh、zh-Hant、es、pt-BR、vi、id、ja。如果不传 lang，收银台会尽量匹配用户的浏览器语言，并兜底为英文。

支持的钱包方式

收银台支付页支持以下三种支付方式，用户可根据场景自由选择。

浏览器钱包（桌面）

页面自动检测已注入的钱包提供者并连接，用户确认交易后发送。

• EVM 链：支持 MetaMask、Rabby 等通过 window.ethereum 注入的钱包，共 12 条链。
• Solana：支持 Phantom 等通过 window.phantom.solana 注入的钱包，主网 + devnet。
• TRON：支持 TronLink 等通过 window.tronLink.tronWeb 注入的钱包，主网 + Nile。

手机钱包（WalletConnect）

需要创建会话时传入 walletConnectProjectId。收银台展示手机钱包列表，用户选择后通过 WalletConnect 二维码或深链连接并签名。支持 EVM、Solana 和 TRON 链——TRON 通过 WalletConnect 请求钱包对转账交易签名，收银台再广播上链。

兼容的钱包：MetaMask、Trust Wallet、Coinbase Wallet、OKX、Binance Wallet、TokenPocket、TronLink、Rainbow、Zerion、Ledger Live，以及任意 WalletConnect 兼容钱包。收银台会按订单的链族过滤钱包；TRON 订单展示支持 TRON 的钱包：Trust Wallet、TokenPocket、TronLink。

Solana 和 TRON 的钱包支付需要 RPC 节点来构造并广播转账交易，收银台已自动处理：主网订单经 StableOps 后端 RPC 代理转发，但测试网订单（Solana Devnet、TRON Nile）直连公共 RPC 节点，免费但偶尔可能限流，如果测试网支付构造失败，稍候重试即可。

手动转账

任何场景都可用。用户从页面上复制收款地址，在自己选择的任意钱包或交易所发送，scanner 按收款地址匹配入金。

后端创建会话

import { StableOps } from '@stableops/api-sdk'

const stableops = new StableOps({
  apiKey: process.env.STABLEOPS_API_KEY!,
})

const merchantOrderId = 'order_123'
const checkout = await stableops.checkoutSessions.create(
  {
    merchantOrderId,
    amount: '49.00',
    amountMode: 'auto',
    acceptedAssets: [{ chain: 'base-sepolia', asset: 'USDC' }],
    expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
    title: 'StableOps Starter Plan',
    successUrl: `https://stableops.dev?result=success&orderId=${merchantOrderId}`,
    cancelUrl: `https://stableops.dev?result=canceled&orderId=${merchantOrderId}`,
    walletConnectProjectId: process.env.WALLETCONNECT_PROJECT_ID,
  },
  { idempotencyKey: 'order_123' },
)

return Response.redirect(checkout.url!, 303)

参数建议

• merchantOrderId：使用你系统里的订单号，并同时作为幂等键，避免重复创建。
• amountMode: 'auto'：让 StableOps 自动微调金额，降低共享收款地址下的撞单概率。
• acceptedAssets：先从测试网资产开始；生产环境再切到你实际支持的主网资产。
• successUrl / cancelUrl：只用于用户体验。最终业务状态以 webhook 为准。
• walletConnectProjectId：可选，可在 Reown Cloud 免费注册获取。传入后，收银台展示手机钱包入口，EVM、Solana 和 TRON 链均通过 WalletConnect 二维码或深链连接手机钱包签名：
  • EVM 和 Solana 链：MetaMask、Trust Wallet、Coinbase、OKX、Binance Wallet、Rainbow、Zerion、Ledger Live 及通用 WalletConnect。
  • TRON 链：Trust Wallet、TokenPocket、TronLink。钱包通过 WalletConnect 对转账交易签名，收银台再广播上链。
  • 不传时不展示手机钱包入口（EVM / Solana / TRON 均不展示）；用户仍可用浏览器注入钱包或手动转账支付。
• metadata：可以放套餐、用户 ID、内部订单标签等，但公开收银台不会展示订单元数据。

在线测试

下面的测试面板会直接在浏览器里使用你的 sandbox API key 创建收银台会话，并跳转到公开收银台页面。你可以自定义商户订单号、金额、标题、描述、返回地址和订单元数据，方便验证商户侧参数会如何进入支付页。

安全注意

• 这个面板只用于 sandbox 测试。生产环境请在你的后端创建收银台会话，不要在浏览器暴露 live API key。
• clientSecret 是打开公开支付页的凭证，只应该发送给本次付款用户。
• 收银台页面只读取公开会话，不需要 Clerk 登录，也不会暴露订单元数据。

处理 Webhook

收银台与 SDK 流程走的是同一套支付订单，支付状态始终通过 Webhook 到达——不要只信任 successUrl 跳转。

• Webhooks —— 事件类型、负载结构、投递/重试行为。
• 验证 Webhook 签名 —— 在解析 body 前校验 X-Product-Signature。
• Webhook 排障 —— 排查漏投/失败的投递。