Checkout Button 与 Checkout Panel

如果你的目标是在自己的网站结算页增加 Taria Pay 支付入口，优先按三档选择：

方式	适合谁	页面里发生什么
Hosted Checkout	不想维护支付 UI，或想最低风险上线	跳转到 checkoutUrl / checkout.tariapay.com/...
Checkout Button	想在自己页面放一个支付按钮	按钮点击后打开 Hosted Checkout
Checkout Panel	想让买家留在自己页面内完成钱包支付	页面内嵌钱包连接、链/币种选择和支付面板

大多数商家先用 Hosted Checkout 或 Checkout Button。Checkout Panel 是高级集成，适合有前端工程能力、愿意测试钱包兼容性和浏览器行为的团队。

Checkout Button

Checkout Button 是最轻量的网页内集成。它不把钱包连接、RainbowKit、wagmi 或链上交易逻辑搬进你的网站；它只负责在买家点击后打开你服务端返回的 hosted checkout URL。

安装

npm install @tariapay/checkout-panel

在渲染按钮的入口引入样式：

import "@tariapay/checkout-panel/styles.css";

服务端创建支付订单

API key 只能放在服务端。前端不应该直接创建 payment intent。

import { NextResponse } from "next/server";
import { TariaPay } from "@tariapay/sdk";

const tariapay = new TariaPay({
  secretKey: process.env.TARIAPAY_SECRET_KEY!,
});

export async function POST() {
  const paymentIntent = await tariapay.paymentIntents.create({
    orderId: `order_${crypto.randomUUID()}`,
    amount: "49.99",
    currency: "USDC",
    successUrl: "https://merchant.example/success",
    cancelUrl: "https://merchant.example/cancel",
  });

  return NextResponse.json({
    checkoutUrl: paymentIntent.checkoutUrl,
  });
}

前端渲染按钮

"use client";

import { CheckoutButton } from "@tariapay/checkout-panel/button";
import "@tariapay/checkout-panel/styles.css";

export function TariaPayButton() {
  return (
    <CheckoutButton
      createCheckout={async () => {
        const response = await fetch("/api/tariapay/create-payment", {
          method: "POST",
        });
        if (!response.ok) throw new Error("Failed to create checkout");
        return (await response.json()) as { checkoutUrl: string };
      }}
    >
      Pay with Taria Pay
    </CheckoutButton>
  );
}

如果你的页面已经有 checkoutUrl，也可以直接传：

<CheckoutButton checkoutUrl={checkoutUrl}>Pay with Taria Pay</CheckoutButton>

Checkout Panel

Checkout Panel 会把钱包连接、链/币种选择、授权与支付按钮放在你的页面内。它适合你明确希望买家不离开自己的网站，并且能维护前端依赖和钱包测试的场景。

安装高级依赖

npm install @tariapay/checkout-panel @rainbow-me/rainbowkit wagmi viem @tanstack/react-query

服务端返回 paymentId

return NextResponse.json({
  paymentId: paymentIntent.paymentId,
});

前端渲染面板

"use client";

import { CheckoutPanel } from "@tariapay/checkout-panel";
import "@tariapay/checkout-panel/styles.css";

export function TariaPayCheckoutPanel({ paymentId }: { paymentId: string }) {
  return (
    <CheckoutPanel
      paymentId={paymentId}
      walletConnectProjectId={process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID}
      onSuccess={({ txHash }) => {
        window.location.assign(`/success?tx_hash=${txHash}`);
      }}
    />
  );
}

walletConnectProjectId 不是浏览器钱包扩展的硬性要求，但如果你希望手机钱包和 WalletConnect 钱包体验稳定，建议配置。

什么时候选择哪一个

• 没有开发能力，或只想最快上线：使用 Hosted Checkout / 收款链接。
• 有一个自己的网站结算页，但不想维护钱包逻辑：使用 Checkout Button。
• 想让买家留在自己页面内完成钱包支付：使用 Checkout Panel。
• 要完全自定义钱包和链上交互：使用 API 参考 自己实现前端流程。

履约规则

浏览器回调、按钮跳转和成功页都只用于买家体验，不能替代服务端确认。

你的系统应该在 webhook 验签通过后再发货、开通会员、记账或释放库存。继续阅读：接收支付结果。

下一步

• 创建支付订单：创建支付订单
• Hosted Checkout：跳转到结账页
• 测试与上线：测试与上线准备