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	获取单个支付订单（已分配收款地址后附带 transferDepositAddress + transferInstructions）
GET	/payment-intents/:paymentId/transfer-status	自己订单的直接转账状态：已收金额、少付/多付、错链或错币、过期后到账。?scanAllChains=true 同时读取其他已启用的链。见程序化付款
GET	/payment-intents/:paymentId/transfer-deposit	自己订单的收款地址余额，严格只读（从不触发检测）
POST	/payment-intents/:paymentId/transfer-deposit/settle	立即结算已足额的入金，不等后台扫描
POST	/payment-intents/:paymentId/expire	让一笔未支付、未收到入金的订单过期
GET	/payment-status?orderId=	按你的 orderId 查询自己订单的链上支付状态（取代公开的 merchant + orderId 查询）
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	转账支付：查询专属收款地址的到账状态

公开 checkout 数据只包含买家页面需要的内容——金额、状态、网络、displayReference、publicMetadata——不含你的 orderId、返回地址或私有 metadata。GET /checkout/v1/payment-intents/:paymentId/return?outcome=success|cancel 是结账页把买家送回你网站的入口。GET /public/payment-status 只接受 paymentId 或 txHash 查询并有限速，按 txHash 查询只返回链上字段。

这些公开接口的 :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，主币种
acceptedCurrencies	可选	USDC / USDT / EURC 数组，控制结账页币种选择。不传则只显示 currency。
customer	可选	{ email?, name? }（兼容 customerEmail / customerName）
successUrl	推荐	支付后返回商家网站的地址；支付进入处理中或已确认后由服务端跳转，不会暴露给结账页
cancelUrl	推荐	取消支付后返回商家网站的地址
displayReference	可选	展示给买家的订单参考号，最多 64 个可打印字符；orderId 不会展示
publicMetadata	可选	展示给买家的键值对，最多 10 个（键 [A-Za-z0-9_.-]{1,40}，值不超过 200 字符）
metadata	可选	商户自定义键值对，只对你可见（webhook、后台、API）
paymentMethods	可选	{ wallet?, transfer?, transferDefaultOpen? }，控制结账页付款方式展示，详见创建支付订单
deferTransferDeposit	可选	REST API 布尔值，默认 false。跳转式收银台可设为 true，将收款地址准备延后至收银台加载，减少创建请求等待；创建响应可能不含 transferDepositAddress。固定客户地址的占用检查仍在创建时完成。
metadata.fixed_transfer_customer_id	可选	已验证身份老客户的客户 ID——其订单复用同一个固定转账收款地址（SDK 对应 fixedTransferCustomerId 字段），详见老客户固定收款地址
expiresAt	可选	ISO-8601 时间戳。没有上限也没有默认值（不传 = 不会自行过期）；程序付款请给一小时以上

可选请求头：Idempotency-Key（1–255 个可打印 ASCII 字符，按商户隔离）。同 key + 同请求体 → 返回原订单，HTTP 200，idempotentReplay: true；同 key + 不同请求体 → HTTP 409，错误码 idempotency_key_reused；不可用的 key → HTTP 400，错误码 invalid_idempotency_key。

响应结构

{
  "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"
  }
}

创建响应在 paymentIntent 之外还带 paymentConfig、availableChains、付款方式标记，以及（默认分配了直接转账收款地址时，deferTransferDeposit: true 除外）transferDepositAddress 与结构化的 transferInstructions（地址、过期时间、每条链的代币合约、小数位与精确最小单位金额、给付款方的规则）。查询响应在地址存在后也带这两个字段。

支付订单 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 已存在；或错误码 fixed_transfer_active_payment——该客户的固定收款地址仍被另一笔未支付订单占用（先引导完成或取消那笔订单）
422	商户可用余额不足以完成退款
500	服务端错误，请记录 requestId 后联系支持

下一步

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