Taria Pay 文档

Appearance

商家接入说明：把 Taria Pay 接到你的网站 ​

这页写给“已经有网站、购物车或订单系统”的商家。首选路径是：

@tariapay/sdk 放在你的服务端 -> 创建 payment intent -> 前端跳转到 Taria Pay 支付订单 checkout -> 用 webhook 回写订单状态。

适合谁 ​

  • 你已经有网站、购物车或结账页
  • 你希望保留自己的订单号、订单状态和客户上下文
  • 你想把 Taria Pay 作为网站里的一个正式支付方式

如果你暂时不想改网站代码，先看：

接入前准备 ​

在开始前，先确认你已经有：

  • 一个 Taria Pay 商家账户
  • Dashboard 里的唯一“商户标识”
  • Developers 页里创建好的 API key
  • 一个可以对外发请求的商家服务端
  • 你自己网站里的成功页和取消页地址

重要原则：

  • API key 只能放在你的服务端，不能放浏览器
  • 商家不需要提交任何商户归属地址字段
  • merchantRefAddress 由 Taria Pay 根据你的商户标识自动派生
  • 当前资金路径是“买家付款 -> 平台 treasury 收款”，merchantRefAddress 只用于订单归属和链上事件标记

标准接入架构 ​

text
你的前端页面
  -> 调用你的服务端
你的服务端
  -> @tariapay/sdk
  -> POST https://api.tariapay.com/v1/payment-intents
  -> 返回 checkoutUrl
用户浏览器
  -> 跳转到 Taria Pay 支付订单 checkout
Taria Pay
  -> 完成支付
  -> 通过 webhook 或查询接口回写状态
你的订单系统
  -> 更新订单结果

一句话理解：

你的系统负责“创建订单和保存业务上下文”，Taria Pay 负责“承接支付页面和完成链上付款”。

6 步完成接入 ​

Step 1：创建商家账户并确认商户标识 ​

先在 Dashboard 完成注册和登录。进入设置页后，你会看到自己的“商户标识”。

这个标识会被 Taria Pay 用来绑定你的 API key、订单和内部派生的 merchantRefAddress。你不需要自己生成或提交链上归属地址。

Step 2：在 Developers 页面创建 API key ​

进入 Dashboard 的 Developers 页面：

  1. 创建一个 test API key 先联调
  2. 上线前再创建 live API key
  3. 把 key 保存到你自己的服务端环境变量

如果你想走正式 SDK 接入，直接看 Developers 页里的 JavaScript SDK。

Developers 页面里最常用的几个区块分别负责：

  • JavaScript SDK：复制服务端创建支付、前端跳转 checkout、webhook 验签示例
  • API Keys：创建和吊销 test / live key
  • Webhooks：创建回调地址并保存 whsec_... signing secret
  • Delivery Logs：查看回调成功、失败、重试次数和最后错误信息

Step 3：在服务端安装 SDK ​

bash
npm install @tariapay/sdk

最小环境变量：

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

本地联调时可以把 TARIAPAY_API_BASE_URL 指向自己的后端；正式环境默认走 https://api.tariapay.com/v1/*。

Step 4：由你的服务端创建 payment intent ​

你的服务端需要决定：

  • 商户订单号 orderId
  • 金额 amount
  • 币种 currency
  • 成功和取消跳转地址
  • 需要透传的业务信息 metadata

最小服务端示例：

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

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

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

return paymentIntent.checkoutUrl;

如果你的当前部署启用了多链 checkout，买家进入 checkoutUrl 后会自动看到当前环境里可执行的支付链选择。商家服务端不需要在创建 payment intent 时额外传 chainId。

Step 5：前端只拿 checkoutUrl 并跳转 ​

浏览器端不需要知道 API key，也不应该直接调用 Taria Pay API。

最小前端示例：

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

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

Step 6：接收支付结果并更新你的订单 ​

推荐主链路：

  • 配置 webhook，让 Taria Pay 主动把支付状态变化推给你

推荐兜底链路：

  • GET /v1/payment-intents/:paymentId
  • GET /v1/payment-intents?orderId=...
  • GET /public/payment-status?txHash=<tx-hash>

你的订单系统至少需要能处理：

  • 支付成功
  • 支付失败
  • 处理中或确认中
  • 用户取消返回

更具体地说，建议把这些状态和业务动作分开：

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

重要提醒：

  • successUrl 和 cancelUrl 只负责前端体验，不应替代最终支付结果
  • webhook handler 要先验签，再更新订单状态
  • webhook 更新要幂等，避免重复发货或重复开通权益

上线前检查清单 ​

  • Dashboard 里已经创建可用的 test API key
  • 你的服务端已经安装并能正常调用 @tariapay/sdk
  • 浏览器端不会暴露 API key
  • 前端收到 checkoutUrl 后能正确跳转
  • successUrl 和 cancelUrl 都指回你自己的网站
  • 你已经配置 webhook，或至少准备好查询兜底逻辑
  • 你知道测试环境和正式环境分别用哪一个 key
  • 你知道如何在 Developers -> Delivery Logs 里排查 webhook 失败与重试

常见误区 ​

误区 1：把 API key 放到前端 ​

不要这么做。API key 只能放在你的服务端。

误区 2：以为商家要提交商户地址 ​

不需要。商家侧不需要提交任何商户归属地址字段。Taria Pay 会根据你的商户标识自动派生内部使用的 merchantRefAddress。

误区 3：只做前端跳转，不做结果回写 ​

如果你的网站里有订单状态，就一定要配 webhook 或查询兜底，否则支付成功后你的内部订单很可能不会及时更新。

误区 4：把支付订单、Paylink、Subscription 混在一起理解 ​

如果你已经有网站，绝大多数情况下先用支付订单就够了。Paylink 和 Subscription 更适合链接收款或固定套餐场景。

下一步阅读 ​