创建支付订单

支付订单用于把你网站里的业务订单连接到 Taria Pay 支付流程。你的服务端创建 payment intent 后，会得到 paymentId 和 checkoutUrl。

使用 Hosted Checkout 时，前端跳转到 checkoutUrl。
使用 Checkout Button 时，前端按钮打开 checkoutUrl。
使用 Checkout Panel 时，前端把 paymentId 传给 <CheckoutPanel />。

请求由谁发起

必须由你的服务端发起。不要从浏览器直接调用 Taria Pay API，也不要把 API key 放到前端、移动端包或公开仓库里。

字段	是否必填	说明
`orderId`	必填	你自己系统里的订单号，同一商户下必须唯一
`amount`	必填	订单金额，建议使用字符串
`currency`	必填	`USDC`、`USDT` 或 `EURC`，主币种
`acceptedCurrencies`	可选	结账页还可选的币种，例如 `["USDC","USDT"]`。主币种会自动包含。不传则只显示 `currency`。
`successUrl`	推荐	买家支付后返回你网站的地址
`cancelUrl`	推荐	买家取消支付后返回你网站的地址
`customer`	可选	买家邮箱、姓名等信息
`metadata`	可选	你的业务上下文，例如购物车 ID
`paymentMethods`	可选	控制结账页展示哪些付款方式，见下文
`fixedTransferCustomerId`	可选	为已验证身份的老客户启用固定收款地址，见下文
`expiresAt`	可选	订单过期时间，ISO-8601 格式

SDK 示例

const paymentIntent = await tariapay.paymentIntents.create({
  orderId: "order_1001",
  amount: "12.50",
  currency: "USDC",
  acceptedCurrencies: ["USDC", "USDT"],
  successUrl: "https://merchant.example/success",
  cancelUrl: "https://merchant.example/cancel",
  customer: {
    email: "buyer@example.com",
    name: "Alice",
  },
  metadata: {
    cartId: "cart_12",
  },
});

return {
  paymentId: paymentIntent.paymentId,
  checkoutUrl: paymentIntent.checkoutUrl,
};

REST 示例

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

控制结账页的付款方式

默认情况下，结账页同时提供钱包支付和直接转账（在支持的网络上），转账区默认收起。你可以在创建支付订单时用可选的 paymentMethods 字段调整：

json

{
  "orderId": "order_1001",
  "amount": "12.50",
  "currency": "USDC",
  "paymentMethods": {
    "wallet": true,
    "transfer": true,
    "transferDefaultOpen": true
  }
}

字段	默认值	说明
`wallet`	`true`	是否展示"连接钱包"付款模块
`transfer`	`true`	是否提供直接转账；设为 `false` 时服务端也会拒绝该订单的转账请求
`transferDefaultOpen`	`false`	转账区是否默认展开；`wallet: false` 时自动展开

规则与兜底：

wallet 和 transfer 不能同时为 false，否则返回 400。
两个开关都在服务端强制，不只是隐藏界面：关掉的方式对应的接口会返回 403。
直接转账仍受网络支持范围约束。如果你设置了 wallet: false，但订单当前所在的网络不支持转账，结账页会自动回落展示钱包模块，并允许在该网络上用钱包付款，保证买家始终有可用的付款方式；买家切换到支持转账的网络后，钱包模块会重新隐藏。
不传该字段时行为与现在完全一致，已有接入无需任何改动。

老客户固定收款地址

默认情况下，每笔订单都会分配一个全新的、不复用的转账收款地址。对于已验证身份的老客户，你可以改为给每位客户一个固定收款地址：该客户的所有订单、所有受支持的网络都使用同一个地址。常从交易所付款的回头客可以把地址存入交易所地址簿，不必每次重新复制新地址。

创建订单时传入你自己系统里的客户 ID：

const paymentIntent = await tariapay.paymentIntents.create({
  orderId: "order_1001",
  amount: "12.50",
  currency: "USDC",
  fixedTransferCustomerId: "user_42", // 你的客户 ID，仅限已验证账号
})

用 REST 时改为设置保留 metadata 键（SDK 字段做的就是这件事）：

json

{
  "orderId": "order_1001",
  "amount": "12.50",
  "currency": "USDC",
  "metadata": {
    "fixed_transfer_customer_id": "user_42"
  }
}

规则与责任：

只为你已验证身份的客户传入该字段——已登录且邮箱通过验证的账号、钱包签名登录，或等效的校验。买家会长期信任这个地址属于自己，因此绝不能用未经验证的输入（比如买家随手填的邮箱）推导资格。访客和未验证用户直接不传即可，他们继续使用每单一个的新地址。
地址按「你的商户账号 + 你传的客户 ID」隔离。请使用你系统里稳定、不含个人信息的 ID（用户 ID，而不是可能变更的邮箱）。
同一时刻只允许一笔未支付订单使用该地址。 客户已有一笔未支付订单占用固定地址时，用同一个 fixedTransferCustomerId 再创建订单会返回 409，错误码 fixed_transfer_active_payment。此时应引导客户完成或取消上一笔订单，而不是重试——保存了 orderId 的话可以用 retrieveByOrderId 找回。
只有订单开着期间转入的资金才计入该订单。 每笔新订单都会先在地址上记录一个余额基准点，订单创建之前（或两笔订单之间）到账的资金不会自动计入后面的订单。请提示买家先下单再转账；如果资金转在了订单之外，请联系我们协助找回。
钱包支付不受影响：结账页照常提供两种付款方式，支付结果和 webhook 事件也完全一致。
固定地址只改变转账支付使用哪个收款地址，其余一切——确认、错链救援、webhook、转账退款流程——都与普通直接转账相同（见支持的付款方式）。

重要规则

一个支付订单同时支持钱包支付和直接转账（结账页展示订单专属收款地址），无需传任何付款方式相关字段；两种方式的支付结果和 webhook 事件完全一致。想调整展示方式见上文 paymentMethods，更多背景见支持的付款方式。
orderId 对同一商户必须唯一。
重复创建相同 orderId 通常会返回冲突错误。创建超时时请 retrieveByOrderId，不要换新的 id。
checkoutUrl 形如 https://checkout.tariapay.com/pi_<uuid>，请原样使用接口返回值，不要自行拼接结账 URL。paymentId 本身是不带前缀的 UUID。
商家不需要提交链上归属地址。
通常不需要在创建支付订单时传 chainId，结账页会展示当前可用的支付网络。
不要用 successUrl 当作最终支付结果。

下一步

前端如何处理：跳转到结账页
支付按钮或 Checkout Panel：Checkout Button 与 Checkout Panel
支付后如何更新订单：接收支付结果

创建支付订单 ​

请求由谁发起 ​

推荐字段 ​

SDK 示例 ​

REST 示例 ​

控制结账页的付款方式 ​

老客户固定收款地址 ​

重要规则 ​

下一步 ​