Taria Pay 文档

Appearance

Merchant API 概览 ​

这页属于高级接入参考，适合需要由自己服务端控制订单创建、查询和状态回写的商家。

正式开发者接口基础地址是：

bash
https://api.tariapay.com/v1

本地开发默认可以把 base URL 指向：

bash
http://localhost:8080

认证方式 ​

正式接入推荐：

  • Authorization: Bearer tpk_...

兼容写法：

  • x-api-key: tpk_...

API key 缺失、已撤销或 hash 不匹配时，接口返回 401。

核心接口 ​

方法路径作用
POST/v1/payment-intents创建新的支付订单
GET/v1/payment-intents列出订单，或按 orderId 查询
GET/v1/payment-intents/:paymentId获取单个订单详情

创建 payment intent ​

bash
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",
    "customer":{
      "email":"[email protected]",
      "name":"Alice"
    },
    "successUrl":"https://merchant.example/success",
    "cancelUrl":"https://merchant.example/cancel",
    "metadata":{"cartId":"cart_12"}
  }'

请求字段 ​

字段是否必填说明
orderId必填商户业务系统订单号
amount必填支持字符串或数字
currency必填当前支持 USDC、USDT、EURC
customer可选{ email?, name? }
successUrl可选支付成功跳转地址
cancelUrl可选用户取消跳转地址
metadata可选商户自定义键值对
expiresAt可选ISO-8601 时间戳

重要规则 ​

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

响应结构 ​

创建和单条查询接口都会返回：

json
{
  "paymentIntent": {
    "paymentId": "pi_123",
    "id": "pi_123",
    "status": "requires_payment",
    "orderId": "order_1001",
    "amount": "12.50",
    "currency": "USDC",
    "checkoutUrl": "https://checkout.tariapay.com/checkout/payment-intents/pi_123",
    "successUrl": "https://merchant.example/success",
    "cancelUrl": "https://merchant.example/cancel",
    "customer": {
      "email": "[email protected]",
      "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"
  }
}

错误结构 ​

/v1/* 接口统一返回：

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

推荐用法 ​

  1. 商户后端创建 payment intent
  2. 仅把 paymentIntent.checkoutUrl 返回前端
  3. 用 webhook 同步最终状态

相关文档：