API 参考

Merchant API 用于由商家服务端创建和查询支付订单。API key 必须保存在服务端。

Base URL

https://api.tariapay.com/v1

认证

推荐使用 Bearer token：

Authorization: Bearer tpk_...

兼容写法：

x-api-key: tpk_...

API key 缺失、无效或已撤销时，接口会返回 401。

核心接口

方法	路径	作用
POST	/payment-intents	创建新的支付订单
GET	/payment-intents	列出订单，或按 orderId 查询
GET	/payment-intents/:paymentId	获取单个支付订单
POST	/payment-intents/:paymentId/refunds	将已确认支付全额退回原付款钱包
GET	/refunds	列出商户退款记录

公开 Checkout 接口

这些接口由 Hosted Checkout、Checkout Button 和 Checkout Panel 使用，普通商户通常不需要直接调用。Button 路径只需要你的服务端返回 checkoutUrl；Panel 路径才需要把 paymentId 传给前端。

方法	路径	作用
GET	/checkout/v1/payment-intents/:paymentId	读取公开 checkout 数据
POST	/checkout/v1/payment-intents/:paymentId/attempts	买家选定网络和币种后创建本次支付配置
POST	/checkout/v1/payment-intents/:paymentId/sync	买家提交交易后同步链上收据
POST	/checkout/v1/payment-intents/:paymentId/transfer-status	转账支付：查询专属收款地址的到账状态

这些公开接口的 :paymentId 同时接受不带前缀的 UUID 和 pi_<uuid> 形态。历史的 /prepare 接口仅为兼容保留，新集成不要使用。

订阅接口

用于有自己客户系统的商户管理订阅，详见订阅接入（API）。

方法	路径	作用
POST	/subscription-plans	创建套餐（价格对象）
GET	/subscription-plans	列出套餐
GET	/subscription-plans/:planId	获取单个套餐
PATCH	/subscription-plans/:planId	更新套餐
POST	/subscriptions	为某个客户开订阅，返回订阅、invoice 和付款链接
GET	/subscriptions	列出订阅，支持 customerId / planId 过滤
GET	/subscriptions/:id	获取单个订阅
GET	/subscriptions/:id/invoices	列出订阅的账期 invoice
POST	/subscriptions/:id/cancel	取消订阅

创建支付订单

curl -X POST "https://api.tariapay.com/v1/payment-intents" \
  -H "Authorization: Bearer tpk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_1001",
    "amount": "12.50",
    "currency": "USDC",
    "successUrl": "https://merchant.example/success",
    "cancelUrl": "https://merchant.example/cancel",
    "customer": {
      "email": "buyer@example.com"
    },
    "metadata": {
      "cartId": "cart_12"
    }
  }'

请求字段

字段	是否必填	说明
orderId	必填	商户业务系统订单号
amount	必填	订单金额，建议使用字符串
currency	必填	USDC、USDT 或 EURC
customer	可选	{ email?, name? }
successUrl	推荐	支付后返回商家网站的地址
cancelUrl	推荐	取消支付后返回商家网站的地址
metadata	可选	商户自定义键值对
paymentMethods	可选	{ wallet?, transfer?, transferDefaultOpen? }，控制结账页付款方式展示，详见创建支付订单
expiresAt	可选	ISO-8601 时间戳

响应结构

{
  "paymentIntent": {
    "paymentId": "b1985d0b-2026-4f8c-bf75-59ea53fe5466",
    "id": "b1985d0b-2026-4f8c-bf75-59ea53fe5466",
    "status": "requires_payment",
    "orderId": "order_1001",
    "amount": "12.50",
    "currency": "USDC",
    "checkoutUrl": "https://checkout.tariapay.com/pi_b1985d0b-2026-4f8c-bf75-59ea53fe5466",
    "successUrl": "https://merchant.example/success",
    "cancelUrl": "https://merchant.example/cancel",
    "customer": {
      "email": "buyer@example.com",
      "name": "Alice"
    },
    "metadata": {
      "cartId": "cart_12"
    },
    "txHash": null,
    "paidAt": null,
    "expiresAt": null,
    "createdAt": "2026-03-30T00:00:00.000Z",
    "updatedAt": "2026-03-30T00:00:00.000Z"
  }
}

支付订单 ID 与结账 URL

• paymentId 是不带前缀的 UUID。调用 Merchant API（查询、退款）时请使用这个值。
• checkoutUrl 是带类型前缀的结账地址，形如 https://checkout.tariapay.com/pi_<uuid>（收款链接为 pl_、订阅套餐为 su_）。请把它原样交给买家跳转，不要自行拼接结账 URL——路径形态可能随版本调整，接口返回的 checkoutUrl 永远是权威形态。
• 你之前保存或分享过的旧形态结账链接（如 /payment-intents/<uuid>、/paylink/<slug>）继续有效，不会失效或跳转。

发起退款

退款必须从商户服务端调用。当前接口执行全额原路退款：链、币种、金额和目标钱包都来自已确认的原支付，调用方不能覆盖退款地址。

const refund = await tariapay.paymentIntents.refund(
  "b1985d0b-2026-4f8c-bf75-59ea53fe5466",
  { reason: "Customer canceled the order" },
);

curl -X POST "https://api.tariapay.com/v1/payment-intents/b1985d0b-2026-4f8c-bf75-59ea53fe5466/refunds" \
  -H "Authorization: Bearer tpk_..." \
  -H "Content-Type: application/json" \
  -d '{"reason":"Customer canceled the order"}'

退款会先从商户对应链和币种的可用余额中原子预留资金。余额不足返回 422；链上提交后返回 processing 或 completed，重复请求不会重复转账。

错误结构

{
  "error": {
    "type": "invalid_request_error",
    "code": "order_id_conflict",
    "message": "orderId already exists for merchant",
    "requestId": "req_123"
  }
}

常见错误

状态码	常见原因
400	请求字段缺失或格式不正确
401	API key 缺失、无效或已撤销
409	orderId 已存在
422	商户可用余额不足以完成退款
500	服务端错误，请记录 requestId 后联系支持

下一步

• 接入步骤：快速接入
• 支付按钮或 Checkout Panel：Checkout Button 与 Checkout Panel
• 支付结果：接收支付结果