快速接入

这页适合已经有网站、购物车、订单系统或会员系统的商家。目标是在你的服务端创建支付订单，并把买家跳转到 Taria Pay 托管结账页。

如果你已经有自己的结算页，可以用 Checkout Button 打开同一个 hosted checkout；如果你希望买家完全留在你的网站内支付，再使用 Checkout Panel。

标准流程

你的前端
  -> 调用你的服务端
你的服务端
  -> 创建 payment intent
  -> 返回 checkoutUrl
买家浏览器
  -> 跳转到 Taria Pay 结账页
Taria Pay
  -> 完成付款
  -> 通过 webhook 通知结果
你的系统
  -> 更新订单并履约

开始前准备

你需要：

• 一个 Taria Pay 商家账户
• 一个 test API key
• 一个可以调用 Taria Pay API 的服务端
• 你自己网站里的成功页和取消页
• 一个用于接收支付结果的 webhook endpoint

重要原则：

• API key 只能放在服务端，不能放进浏览器代码。
• 前端只负责请求你的服务端并跳转到 checkoutUrl。
• successUrl 只代表买家回到了你的网站，不等于订单已经可以履约。
• 最终支付结果以 webhook 或查询接口为准。

Step 1：安装 SDK

npm install @tariapay/sdk

Step 2：配置环境变量

TARIAPAY_SECRET_KEY=tpk_...
TARIAPAY_WEBHOOK_SECRET=whsec_...
APP_URL=https://merchant.example

本地联调时把 TARIAPAY_API_BASE 设成 API 的 origin（例如 http://127.0.0.1:3003）。SDK 会追加 /v1，不要自己再写 /merchant 或 /v1。

商家应用如果跑在 Cloudflare Workers 上，需要打开 nodejs_compat。SDK 会绑定 fetch。

如果你是 coding agent，请按 接入 Taria Pay（给 coding agent） 做，不要从本页自行发挥。

Step 3：在服务端创建支付订单

import { TariaPay } from "@tariapay/sdk";

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

export async function createCheckout() {
  const paymentIntent = await tariapay.paymentIntents.create({
    orderId: `order_${crypto.randomUUID()}`,
    amount: "49.99",
    currency: "USDC",
    acceptedCurrencies: ["USDC", "USDT"],
    successUrl: `${process.env.APP_URL}/checkout/success`,
    cancelUrl: `${process.env.APP_URL}/checkout/cancel`,
    customer: {
      email: "buyer@example.com",
    },
    metadata: {
      cartId: "cart_789",
    },
  });

  return paymentIntent.checkoutUrl;
}

Step 4：前端跳转到结账页

const response = await fetch("/api/tariapay/create-payment", {
  method: "POST",
});

const payload = await response.json();
window.location.assign(payload.checkoutUrl);

Step 5：用 webhook 更新订单

买家完成付款后，Taria Pay 会把支付状态发送到你的 webhook endpoint。你的系统应该在 webhook 验签成功后更新订单状态。

如果 create 超时，用 tariapay.paymentIntents.retrieveByOrderId(orderId) 查询，不要换一个新的 orderId 再创建。

现象	处理
401	TARIAPAY_SECRET_KEY 错误或已撤销
404	baseUrl 不是 API origin，或服务端还没有 /v1 别名——先用 /merchant/v1 重试
超时（TariaPayError.type === "timeout_error"）	retrieveByOrderId
409	orderId 已存在，改为查询
结账页只有一个币	传 acceptedCurrencies

继续阅读：接收支付结果

下一步

• coding agent 契约：接入 Taria Pay（给 coding agent）
• 详细了解创建参数：创建支付订单
• 只看前端跳转：跳转到结账页
• 支付按钮或 Checkout Panel：Checkout Button 与 Checkout Panel
• 查看接口字段：API 参考