JavaScript SDK 与 Developers 页面

这页对应 Dashboard 里的 /developers，适合“已经有自己的网站、购物车或订单系统”的商家。

如果你要尽快把支付接进现有项目，推荐直接走这条标准路径：

你的服务端 -> @tariapay/sdk -> 创建 payment intent -> 前端跳转 checkout -> webhook 更新订单状态

如果你还没看过整体流程，先读：

• 商家接入说明

这页帮你完成什么

在 Dashboard 的 Developers 页面里，你通常会连续完成这 4 件事：

1. 在 API Keys 创建 test / live key
2. 在 JavaScript SDK 复制服务端、前端和 webhook 示例
3. 在 Webhooks 创建回调地址并保存 signing secret
4. 在 Delivery Logs 看回调成功、重试和失败原因

如果你是“自定义网站接入支付”，这就是最短上线路径。

什么时候用这条接入方式

适合：

• 你已经有自己的网站、购物车、订单系统或会员系统
• 你要保留自己的 orderId、订单状态、客户上下文和履约逻辑
• 你希望把 Taria Pay 作为网站里的正式支付方式，而不是临时收款链接

不太适合：

• 你暂时不想改网站代码，这种情况更适合先看 接入方式总览
• 你更想先用插件快速上线，这种情况可以优先看 WooCommerce 或应用接入路径

推荐架构

你的前端页面
  -> 调用你的服务端
你的服务端
  -> @tariapay/sdk
  -> 创建 payment intent
  -> 返回 checkoutUrl
用户浏览器
  -> 跳转到 Taria Pay checkout
Taria Pay
  -> 完成支付
  -> 通过 webhook 推送状态
你的订单系统
  -> 更新订单、发货、开通权限、记账

最重要的原则只有两条：

• @tariapay/sdk 只能运行在服务端，不能放浏览器
• successUrl 只负责体验，真正的支付结果要以 webhook 或查询接口为准

最短 7 步

Step 1：在 Developers 页面创建 test API key

先在 Dashboard 登录，然后进入 Developers 页面：

1. 在 API Keys 或 JavaScript SDK 区块创建一个 test key
2. 只把它保存到你的服务端环境变量
3. 等联调通过后，再创建 live key 切生产环境

建议：

• 每个环境使用不同 key
• 每个应用或站点单独命名 key，方便排查与吊销
• 不要把 key 暴露在浏览器代码、移动端包或公开仓库里

Step 2：安装 SDK 并准备环境变量

npm install @tariapay/sdk

最小环境变量：

TARIAPAY_SECRET_KEY=tpk_...
TARIAPAY_API_BASE_URL=http://localhost:8080
TARIAPAY_WEBHOOK_SECRET=whsec_...
APP_URL=http://localhost:3000

说明：

• TARIAPAY_SECRET_KEY：在 Developers 页面创建的服务端 key
• TARIAPAY_API_BASE_URL：本地联调时可指向自己的后端；生产环境默认走 https://api.tariapay.com/v1
• TARIAPAY_WEBHOOK_SECRET：在 Developers -> Webhooks 创建 endpoint 后拿到的签名 secret
• APP_URL：你自己网站的基础地址，用来生成成功页和取消页

Step 3：在你的服务端创建 payment intent

推荐由你自己的服务端决定：

• orderId
• amount
• currency
• successUrl
• cancelUrl
• customer
• metadata

Next.js Route Handler 示例：

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

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

export async function POST() {
  const appUrl = process.env.APP_URL ?? "http://localhost:3000";
  const orderId = `order_${crypto.randomUUID()}`;

  const paymentIntent = await tariapay.paymentIntents.create({
    orderId,
    amount: "49.99",
    currency: "USDC",
    successUrl: `${appUrl}/checkout/success`,
    cancelUrl: `${appUrl}/checkout/cancel`,
    customer: {
      email: "[email protected]",
    },
    metadata: {
      cartId: "cart_789",
    },
  });

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

创建 payment intent 时要特别注意

• orderId 对同一商户必须唯一；重复创建会返回 409
• 商家不需要提交任何商户归属地址字段
• merchantRefAddress 由 Taria Pay 在服务端自动派生
• 如果当前部署启用了多链 checkout，买家会在 checkoutUrl 对应的页面自动看到可执行链选择；创建 payment intent 时不需要额外传 chainId

Step 4：前端只负责跳转 checkout

浏览器端不要直接实例化 TariaPay。你只需要调用自己的服务端接口，拿到 checkoutUrl 后跳转。

React 示例：

import { redirectToCheckout } from "@tariapay/sdk/browser";

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

  const payload = await response.json();

  if (!response.ok || !payload.checkoutUrl) {
    throw new Error(payload.error ?? "Failed to create payment intent");
  }

  redirectToCheckout(payload.checkoutUrl);
}

如果你不用 @tariapay/sdk/browser，直接 window.location.assign(payload.checkoutUrl) 也可以。

Step 5：在 Developers 的 Webhooks 里创建回调地址

接入支付时，Webhook 不是可选增强项，而是订单状态回写主路径。

你至少应该在 Developers 页里完成这些操作：

1. 打开 Webhooks
2. 创建你的回调地址，例如 https://merchant.example/api/tariapay/webhook
3. 勾选需要的事件
4. 保存系统返回的 whsec_... signing secret
5. 回到你的服务端，把这个 secret 配到 TARIAPAY_WEBHOOK_SECRET

如果你的网站有订单、发货、开票、会员权限或订阅状态，这一步一定要做。

Step 6：在你的服务端验证 webhook 并更新订单

推荐直接使用 SDK 验签。重点是：

• 读取原始请求体
• 先验签，再解析 payload
• 验签成功后尽快返回 2xx
• 用 paymentId 或 orderId 做幂等更新

Next.js Route Handler 示例：

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

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

export async function POST(req: Request) {
  const rawBody = await req.text();

  const event = tariapay.webhooks.constructEvent(
    rawBody,
    req.headers,
    process.env.TARIAPAY_WEBHOOK_SECRET!,
  );

  const paymentIntent = event.data.paymentIntent;

  switch (event.type) {
    case "payment_intent.confirmed":
      // 标记订单已支付，然后执行发货、开通权限、开票等动作
      break;
    case "payment_intent.failed":
      // 标记订单失败，允许用户重新发起支付
      break;
    default:
      // 其他状态按你的业务选择是否处理
      break;
  }

  return Response.json({ received: true });
}

Step 7：为支付状态和补偿查询留好路径

你的系统至少要能处理这些状态：

状态	推荐业务动作
requires_payment	订单已创建，等待买家进入 checkout
processing	支付已发起但未最终确认，先不要发货
confirmed	订单标记为已支付，执行履约、发货或开通权限
failed	记录失败原因，允许用户重新支付
refunded	同步客服和财务状态，避免内部系统仍显示完成
expired	让用户创建新的 payment intent，不要复用旧 checkout

常用补偿查询方式：

const byPaymentId = await tariapay.paymentIntents.retrieve("pi_123");
const byOrderId = await tariapay.paymentIntents.retrieveByOrderId("order_1001");

如果你拿到的是链上 txHash，再结合 Merchant API 概览 里的查询接口做兜底排查。

接入支付时最容易踩的坑

1. 把 API key 放进前端

不要这么做。TariaPay 这个服务端 SDK 本身就不能在浏览器里实例化。

2. 只做跳转，不做状态回写

如果你的网站里有订单状态，就一定要做 webhook。否则链上支付成功后，你自己的订单系统很容易停留在“待支付”。

3. 用 success 页当最终结果

success 页只能说明“买家回到了页面”，不等于“订单已经可以履约”。真正的业务落账建议以 webhook 的 confirmed 事件或查询结果为准。

4. 没有处理重复事件和重试

Webhook 可能重复投递。订单更新必须幂等，不能因为重复回调就重复发货或重复开通权益。

5. orderId 设计不稳定

orderId 要在你的商户侧稳定且唯一。不要把它做成每次重试都变化的值，否则排障和对账都会变得很困难。

联调清单

• 你已经在 Developers 创建了 test key
• 你的服务端能成功调用 paymentIntents.create
• 前端能拿到 checkoutUrl 并正确跳转
• successUrl 和 cancelUrl 都指回你自己的网站
• 你已经在 Developers 创建 webhook endpoint 并保存 whsec_...
• 你的 webhook handler 能成功验签并返回 2xx
• 你能在自己的系统里看到 paymentId、orderId、状态和最后更新时间
• 你知道如何用 Delivery Logs 和查询接口做补偿排查

上线清单

• 把 test key 换成 live key
• 把测试回调地址换成正式回调地址
• 确认履约、发货、发票和客服流程都以 confirmed 为触发条件
• 确认订单系统可以处理 failed、expired、refunded
• 确认支持团队知道如何通过 paymentId、orderId、txHash 排查问题

Developers 页面里每个标签是做什么的

标签	主要用途
JavaScript SDK	复制安装命令、服务端创建支付示例、前端跳转示例、Webhook 示例
API Keys	创建和吊销 test / live key
Webhooks	创建回调地址、保存 signing secret、查看 endpoint 状态
Delivery Logs	查看回调成功、失败、重试次数和错误信息
WooCommerce	WordPress / WooCommerce 场景的插件化接入

继续阅读

• 先看整体流程：商家接入说明
• 看接口细节：Merchant API 概览
• 看回调与签名：Webhook 与签名校验
• 看本地调试：本地开发环境配置