稳定币结账怎么做？USDC、USDT 收银台与支付 API 集成指南

稳定币结账把业务订单转成清晰的链上付款指令，让客户使用 USDC 或 USDT 付款，并在后端验证最终结果后履约。可靠的收银台需要同时处理金额、资产、网络、收款地址、有效期、钱包交互和付款状态，不能只放一个连接钱包按钮。

如果还在评估是否支持稳定币，先阅读企业接受稳定币支付的完整流程。本文面向已经决定接入的开发团队，重点解决结账界面怎样设计、付款中断怎样恢复，以及什么证据可以触发发货或服务开通。

稳定币结账是什么，应该选择哪种集成模式？

稳定币结账是一段连接订单、钱包转账和商户履约的客户流程。付款链接是进入这个流程的入口，钱包负责签名与发送交易，支付 API 负责订单和状态。它们分别解决不同问题，不能互相替代。

先把页面运行方式和资金控制方式分开。第三方托管结账页面，不代表第三方托管资金。StableOps 提供托管结账页，稳定币直接进入商户控制的地址，商户保管私钥并负责退款签名，不提供自动法币兑换或银行结算。

这是通用集成模式的比较，不代表每个服务商都提供三种现成产品。StableOps 的托管页面可由一次性结账会话进入，自建页面可使用支付订单与钱包 SDK。嵌入方式需要单独评估组件能力和商户自己的开发工作。

固定价格的公开入口适合稳定币付款链接。购物车、客户专属价格和动态税费更适合由后端创建一次性会话。如果业务对象是应收账款，应先设计稳定币发票与支付订单的关联，再决定结账入口。

USDC、USDT 结账页必须展示哪些付款信息？

让付款人可以在签名前核对一份完整指令，并在手机钱包切回浏览器后看到同样的订单。关键信息不要只放在图标、鼠标悬浮提示或钱包弹窗里。

在 StableOps 的支付订单中，金额与有效期位于订单顶层。paymentInstructions 提供候选的链、资产和地址。不要从付款指令对象读取不存在的金额或有效期，也不要把不同候选指令混成一组可任意搭配的选项。

资产必须由网络与合约共同识别。Circle 的 USDC 合约清单分别列出主网和测试网标识，Tether 的支持协议清单列出各网络的 USD₮ 信息。发行方支持某条链，不等于你的支付服务或钱包已经支持它，商户还要核对自己的允许列表。

使用 amountMode: 'auto' 时，StableOps 可能为共享地址上的金额冲突调整最小单位。托管页面展示的是返回的 checkout.paymentOrder.amount，自建页面也必须使用返回值。exact 保留固定金额，但两种模式都要求准确付款，不把少付、多付或拆分转账自动视为成功。

怎样在服务端创建一次性结账会话？

先由商户后端确认客户身份、购物车价格和订单可支付状态，再创建付款尝试。一次创建请求的幂等键与请求正文都必须持久化，重试时原样复用。页面刷新不能成为再次分配地址或创建第二笔待付款订单的理由。

以下是 Next.js 的最小接口结构。loadAuthorizedCheckoutAttempt 和 saveCheckoutMapping 是商户自己的数据库函数，不是 StableOps SDK 方法。前者应校验订单归属，并首次保存完整创建参数。示例使用沙盒 API 密钥和 Base Sepolia USDC，不能把主网资金转入测试指令。

// app/api/checkout/route.ts
import { StableOps } from '@stableops/api-sdk'
import {
  loadAuthorizedCheckoutAttempt,
  saveCheckoutMapping,
} from '@/lib/checkout-store'

export const runtime = 'nodejs'

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

export async function POST(req: Request) {
  // 金额、到期时间和完整请求参数均来自已持久化的付款尝试。
  const attempt = await loadAuthorizedCheckoutAttempt(req)
  const checkout = await stableops.checkoutSessions.create(
    attempt.checkoutRequest,
    { idempotencyKey: attempt.id },
  )

  if (!checkout.url) return new Response('结账暂不可用', { status: 502 })

  await saveCheckoutMapping({
    attemptId: attempt.id,
    checkoutSessionId: checkout.id,
    paymentOrderId: checkout.paymentOrder.id,
    requestedAmount: checkout.paymentOrder.requestedAmount,
    payableAmount: checkout.paymentOrder.amount,
  })

  return Response.json(
    { url: checkout.url },
    { headers: { 'Cache-Control': 'no-store' } },
  )
}

attempt.checkoutRequest 首次写入时应包含以下字段。这里的变量均来自服务端保存的订单与固定配置，不接受浏览器传入的最终价格或任意返回地址。

import type { CreateCheckoutSessionInput } from '@stableops/api-sdk'

const checkoutRequest: CreateCheckoutSessionInput = {
  merchantOrderId: attempt.merchantOrderId,
  amount: order.amount,
  amountMode: 'auto',
  acceptedAssets: [{ chain: 'base-sepolia', asset: 'USDC' }],
  expiresAt: attempt.expiresAt,
  title: order.title,
  successUrl: order.successUrl,
  cancelUrl: order.cancelUrl,
  walletConnectProjectId: process.env.WALLETCONNECT_PROJECT_ID || undefined,
}

金额、标题、有效期、资产列表、返回地址和 WalletConnect 配置都要保存在这份快照中。同一个幂等键不能在重试时搭配重新计算的时间或变化的配置。旧尝试过期后，先确认业务订单尚未结清，再创建独立的新尝试与新幂等键，保留全部尝试到同一业务订单的映射。

前端拿到地址后可以调用 window.location.assign(url)。一次性地址包含访问该付款会话所需的 clientSecret，只交给当前付款人，不写入共享缓存、公开订单列表或统计系统。

商户后端             结账页面与付款钱包          区块链与支付运营层
保存订单与付款尝试
创建会话 ----------> 展示完整付款指令
                     客户核对并签名 ----------> 广播交易
                     显示已提交                 检测、匹配、确认
验证签名并去重 <------------------------------- payment.finalized
原子更新订单并写入履约任务
后台任务幂等履约 ---> 客户订单页展示真实结果

返回页应读取商户后端保存的订单状态。successUrl 和 cancelUrl 都只是浏览器路径，不能直接把订单改为已支付或认定链上转账已经取消。更完整的项目结构见在 Next.js 中接收 USDC。

钱包拒绝、网络错误和付款中断怎样恢复？

恢复流程的目标是保留已经发生的事实，并减少客户不必要的重复付款。区分“尚未广播”和“已经广播但结果未知”，再决定是否可以重新发起。

MetaMask 的网络管理文档列出未添加网络、客户拒绝和请求仍在等待等不同错误。自建页面应根据实际原因反馈，不能全部显示“付款失败”。这些错误是钱包交互结果，不能证明服务器是否已经检测到其他付款。

Ethereum 的网络费说明指出，其交易费使用 ETH 支付。不要因此把所有区块链的手续费资产写成 ETH，所选网络决定实际需求。提币费、网络费和商户服务成本的区别见稳定币支付手续费指南。

对于已广播但结果未知的交易，客服应先核对目标网络、交易哈希、真实代币、接收地址与数量，再决定下一步。关闭页面、断开钱包或点击取消都不会撤销已广播交易。

为什么要用验签后的 Webhook 决定履约？

浏览器跳转和钱包回执由客户环境产生，只适合展示进度。服务端经过验签的支付事件将订单匹配结果与链上确认状态连接起来。对发货、不可逆权益和最终账务记录，StableOps 接入应等待 payment.finalized。

下面展示原始正文验签和持久化交接。recordAndApplyPaymentEvent 是商户需要实现的数据库边界，不能替换成内存集合或“收到事件就调用发货接口”。

// app/api/webhooks/stableops/route.ts
import {
  EVENT_ID_HEADER,
  SIGNATURE_HEADER,
  verifySignature,
} from '@stableops/api-sdk/webhooks'
import { recordAndApplyPaymentEvent } from '@/lib/checkout-store'

export const runtime = 'nodejs'

export async function POST(req: Request) {
  const rawBody = await req.text()
  const verified = verifySignature({
    secrets: [process.env.STABLEOPS_WEBHOOK_SECRET!],
    header: req.headers.get(SIGNATURE_HEADER) ?? undefined,
    rawBody,
  })
  if (!verified.ok) return new Response('签名无效', { status: 400 })

  const eventId = req.headers.get(EVENT_ID_HEADER)
  if (!eventId) return new Response('缺少事件编号', { status: 400 })

  let event: unknown
  try {
    event = JSON.parse(rawBody)
  } catch {
    return new Response('事件正文无效', { status: 400 })
  }

  // 此函数验证事件结构与订单映射，并原子记录事件和业务变更。
  await recordAndApplyPaymentEvent({ eventId, event })
  return new Response('已接收')
}

持久化函数需要验证事件结构，并在同一事务中完成数据库唯一事件编号写入、订单映射核对和合法状态迁移。订单映射必须关联保存的支付订单编号与商户业务引用，不能仅凭客户提交的编号授予权益。只有首次收到且验签通过的 payment.finalized 可以写入不可逆履约任务。给任务增加业务订单级唯一约束，后台执行时也用业务订单编号作为幂等键，避免不同付款尝试导致重复交付。

重复事件应返回成功且没有副作用。数据库提交失败应返回失败，让平台重试。先承诺处理成功，再把事件放到内存中等待履约，会在进程崩溃时丢单。确认策略参见稳定币支付确认指南，事务与任务队列的完整模式见防止 Webhook 重复履约。

稳定币结账转化漏斗应该怎样测量？

按同一批创建的会话统计各阶段，使用会话编号去重，并固定观察截止时间。一次浏览器访问、一次付款尝试和一笔业务订单是不同分母，报表必须写明采用哪一种。

以下是商户自建统计的建议事件模型，不是 StableOps 内置报表的字段清单。

手动转账路径可能没有钱包连接或前端提交事件，却仍然会检测到付款。因此不要把漏斗当成每笔付款必须逐层经过的强制顺序，也不要在分析数据中保存私钥、会话密钥或完整一次性付款地址。

例如，假设某周创建了 1,000 个去重会话，900 个成功加载，截止统计时有 450 个付款最终确定，440 个完成履约：

页面加载率 = 已加载会话数 / 已创建会话数 = 900 / 1,000 = 90%
付款完成率 = 最终确定会话数 / 已创建会话数 = 450 / 1,000 = 45%
已收款履约率 = 已履约会话数 / 最终确定会话数 = 440 / 450 ≈ 97.8%

这些是假设数据，不是产品业绩。正式统计还要处理同一业务订单的重复尝试，并单独记录已收款未履约的业务订单，不能只提高页面点击率。

StableOps 当前结账漏斗按会话记录页面浏览、会话加载、付款开始、交易提交和付款完成等阶段，具体口径以结账文档为准。商户建议模型中的钱包连接、付款检测和业务履约，可能需要自己的埋点或服务端记录。营销统计不能替代收款账本。

稳定币结账上线前应该检查什么？

• API 密钥与 Webhook 密钥只存在于服务端，沙盒与生产配置分别核对。
• 客户身份、订单归属、金额和返回地址均由后端校验。
• 同一次创建重试复用完整参数快照、幂等键和有效期。
• 页面展示返回的精确金额、网络、真实资产标识、地址和过期时间。
• 手机切换、钱包拒绝、网络费不足和手动转账都有可恢复路径。
• 已广播但结果未知时恢复原订单，不自动要求重复付款。
• Webhook 原始正文验签、事件去重、状态更新和履约任务原子提交。
• 乱序事件不会导致状态倒退，不同尝试不会重复履约同一业务订单。
• 迟到、错链、错币和金额异常都有客服入口与可审计记录。
• 返回页只能展示后端订单结果，直接访问成功地址不会发货。
• 漏斗统计注明分母、去重方式、截止时间与手动付款路径。

先用加密支付三层测试方法验证这些条件，再逐步开放更多资产和网络。准备开始集成时，可在沙盒试验场观察一笔真实测试网订单，并按结账文档把同一套指令与最终履约边界接到产品中。

稳定币结账有哪些常见问题？

托管结账页是否意味着资金也被托管？

不一定。页面运行方式和资金路径需要分别确认。StableOps 运行结账页面，稳定币直接到商户控制的收款地址，商户仍负责私钥、金库操作和退款签名。

一次性结账会话和付款链接怎样选择？

固定价格、公开分享的标准服务适合复用付款链接。需要绑定购物车、客户、发票或动态价格时，由后端创建一次性会话更清晰，每个尝试都有独立订单与状态。

付款人必须连接钱包吗？

不必。客户也可以按当前订单指令手动转账。StableOps 托管页面提供浏览器钱包与手动路径，手机 WalletConnect 入口需要创建会话时提供对应配置，并验证目标钱包与网络兼容性。

同一个收银台可以接受 USDC 和 USDT 吗？

可以，但必须列出支付服务实际支持的网络与资产组合。客户选择某个组合后，金额、地址和资产标识都必须来自同一有效指令，不允许仅凭代币符号自行替换。

客户到了成功返回页，可以立即发货吗？

不能。返回地址可以被直接访问，也可能在付款最终确定之前打开。商户后端应通过验签、去重后的 payment.finalized 事件授权不可逆履约，页面只展示已保存的业务状态。

客户关闭页面后，订单还会继续处理吗？

已广播转账仍可能被检测和确认，Webhook 也不依赖浏览器保持打开。客户重新进入订单页时，展示服务端结果，避免因为前端丢失状态而要求再次付款。

支付 API 会自动兑换为法币或退回付款吗？

这取决于提供方的资金与结算模式，不能从“结账 API”推断。StableOps 不托管商户资金，不自动换汇或银行结算，退款需要商户钱包签名后再跟踪独立退款交易。

本文的协议资料与 StableOps 产品行为已于 2026 年 10 月 1 日核验。代码展示接入边界，商户数据库函数需结合自己的订单模型实现。上线前请重新核对官方资产信息、钱包兼容性及当前服务支持范围。