跳到主要内容

标签地址使用说明文档

· 阅读需 4 分钟
UtcPay 支持
UtcPay 支持
UtcPay 商务&支持团队
UtcPay 开发
UtcPay 开发
UtcPay 开发团队

一、功能说明​

标签地址（Tag Address）用于对钱包地址进行分类管理。 商户在创建支付订单时指定 tagName 后，系统会自动从对应标签的地址池中分配收款地址。

地址分配规则如下：

  • 如果标签下存在可用地址，系统优先复用已有地址。
  • 如果标签下地址全部被占用，系统会自动创建新的地址。
  • 新地址会自动归属于该标签。

该机制可以帮助商户实现：

  • 地址分类管理
  • 地址复用
  • 自动地址扩展

该机制适用于需要管理大量订单收款地址的商户场景。

二、整体业务流程​

整体流程如下：

三、创建标签​

文档地址：创建标签接口文档

在创建支付订单之前，商户需要先创建标签。

接口地址：

POST /api/mer/user/tag

请求示例：

{
  "tagName": "A1"
}

该示例创建标签 A1。

创建成功后，该标签即可用于支付订单。

四、创建支付订单​

创建订单时，请在请求参数中填写 tagName，用于指定订单使用的标签地址组。

接口地址：

POST /api/mer/payment/createPaymentOrder

请求示例：

{
  "chainId": 136,
  "description": "A sample order",
  "isLegalTender": 0,
  "notifyUrl": "https://www.payment.com/api/notify",
  "outTradeNo": "C3",
  "quoteAmount": "0.01",
  "quoteCurrencySymbol": "USDT",
  "redirectionUrl": "https://www.payment.com/result?order=202312131805041280413",
  "tagName": "A1"
}

参数说明​

参数名称说明
chainId区块链网络 ID
description订单描述
isLegalTender是否为法币订单
notifyUrl支付成功回调地址
outTradeNo商户订单号
quoteAmount支付金额
quoteCurrencySymbol支付币种
redirectionUrl支付完成后跳转地址
tagName标签名称，用于地址分类

五、地址分配规则​

订单创建成功后，系统会执行以下逻辑：

  1. 获取订单中的 tagName
  2. 查询该标签下的地址池
  3. 判断是否存在可用地址

处理逻辑如下：

  • 如果存在可用地址，优先复用已有地址。
  • 如果地址全部被占用，系统自动创建新地址。

地址分配判断流程：

示例（A1 标签地址池）：

地址1
地址2
地址3
地址4
地址5

订单创建时的地址分配结果：

  • 订单1 -> 地址1
  • 订单2 -> 地址2
  • 订单3 -> 地址3

如果所有地址均被占用，系统将自动创建新地址（例如地址6），并自动加入 A1 标签地址池。

六、修改地址标签​

文档地址：修改地址标签接口文档

如果需要调整某个地址所属的标签，可通过以下接口操作。

1. 查询地址列表​

接口地址：

GET /api/mer/user/list

返回信息中包含以下字段：

  • walletId
  • tagId
  • address

2. 修改地址标签​

接口地址：

POST /api/mer/user/wallet/tag

请求示例：

{
  "walletId": "123456",
  "tagId": "A1"
}

执行成功后，该地址会归属于新的标签。

七、完整流程示例​

完整业务流程示例如下：