接收支付结果

Webhook 是把支付结果同步到你系统的主路径。买家完成付款后，Taria Pay 会把事件发送到你配置的 webhook endpoint。

为什么必须配置 webhook

如果你的网站有订单状态、发货、开票、会员权限或订阅权益，就应该配置 webhook。

不要只依赖：

• 买家是否回到 successUrl
• 前端页面是否显示成功
• 客服人工查看交易

真正的业务落账应以 webhook 或查询接口为准。

创建 webhook endpoint

在商家后台进入 Developers，然后：

1. 打开 Webhooks。
2. 创建 endpoint。
3. 填写你的公网回调地址，例如 https://merchant.example/api/tariapay/webhook。
4. 选择需要接收的事件。
5. 保存 signing secret，并配置到你的服务端环境变量。

建议至少订阅：

• payment_intent.confirmed
• payment_intent.failed

请求头

Header	说明
x-tariapay-signature	HMAC-SHA256 签名
x-tariapay-timestamp	Unix 秒级时间戳
x-tariapay-event	事件名
x-tariapay-delivery-id	单次投递 ID

SDK 验签示例

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

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

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":
      // 用 paymentId 或 orderId 幂等更新订单，然后履约
      break;
    case "payment_intent.failed":
      // 标记订单失败，允许买家重新支付
      break;
    default:
      break;
  }

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

Payload 示例

{
  "id": "evt_123",
  "type": "payment_intent.confirmed",
  "createdAt": "2026-03-29T12:00:00.000Z",
  "data": {
    "paymentIntent": {
      "paymentId": "pi_123",
      "orderId": "order_1001",
      "status": "confirmed",
      "currency": "USDC",
      "amount": "49.99",
      "checkoutUrl": "https://checkout.tariapay.com/checkout/payment-intents/pi_123",
      "txHash": "0x..."
    }
  }
}

处理建议

• 先验签，再处理 payload。
• 使用 paymentId 或 orderId 做幂等更新。
• 尽快返回 2xx，耗时任务放到你的后台队列。
• 处理重复投递，避免重复发货或重复开通权益。
• 在 Delivery Logs 查看失败原因和重试记录。

下一步

• 查看接口字段：API 参考
• 上线前检查：上线检查