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	获取单个支付订单

创建支付订单

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	可选	商户自定义键值对
expiresAt	可选	ISO-8601 时间戳

响应结构

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

错误结构

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

常见错误

状态码	常见原因
400	请求字段缺失或格式不正确
401	API key 缺失、无效或已撤销
409	orderId 已存在
500	服务端错误，请记录 requestId 后联系支持

下一步

• 接入步骤：快速接入
• 支付结果：接收支付结果