• Python
  • Golang
  • Java

# changelog

# v1.0.0

2024-09-25
静态收款地址支付方式接入文档初版

# 1. 功能介绍

静态地址收款方式目标是支持用户在没有Gate账户前提下，可以使用任意钱包资产与Gate商户进行交易

区别于现有"地址支付"，静态收款地址不会为每一笔账单分配一个不同的地址，而是商户事先申请一定数

量的静态地址，用户向静态地址转账，Gate生成支付账单，结算至商户Gate支付账户，并向商户推送用

户支付信息

# 2. 静态收款码支付

# 2.1 安全验证

安全验证参考接口签名

# 2.2 时序图

# 3. 消息通知

# 3.1 向商户发送消息的情形

  • 当商户绑定的收款地址有收入，且收款网络和接收币种在商户营收范围内

# 3.2 静态地址收款消息枚举值

bizType

值 解释
PAY_FIXED_ADDRESS 表示这是一个静态地址收款的通知类型

bizStatus

值 解释
PAY_SUCCESS 支付成功，且到账
PAY_BLOCK Gate成功接收，但资金有风险，不会入账

# 3.3 静态地址收款消息字段

字段名 类型 说明
bizType string 消息提示类型
bizId string 订单号
data string dataType的json编码

dataType

字段名 类型 说明
channelId string 客户名称，只支持字母、数字、下划线和破折号，长度不超过50字节
currency string 账单币种
orderAmount string 账单金额
createTime int 账单创建时间
transactionId string 交易流水号
transactionTime string 账单成交时间
chain string 网络
address string 收款地址
amount string 到账金额

消息结构示例

{
    "bizType": "PAY_FIXED_ADDRESS",
    "bizId": "kt40t9i3t34kt0k09t543932111146",
    "bizStatus": "PAY_SUCCESS",
    "data": "{\"channelId\":\"smart_shop\",\"currency\":\"USDT\",\"amount\":\"5\",\"orderAmount\":\"5\",\"createTime\":1727160132504,\"transactionId\":\"273462465781567488\",\"transactionTime\":1727160132504,\"chain\":\"ETH\",\"address\":\"0xfb8Cdb7da4A1C3fF56Dc7a5d78c8228711E9028F\"}"
}

商户在收到异步回调消息后，需按如下结构响应，returnCode为SUCCESS，否则Gate会认为没有提示成功，响应示例如下

{
    "returnCode": "SUCCESS",
    "returnMessage": ""
}

# 4. 静态收款地址API列表

# 4.1 查询支持的网络和币种

  • 数据类型：JSON （content-type：application/json）
  • 请求⽅式：GET
  • 路径Path: /v1/pay/fixedaddress/chains
  • 验证⽅式：商户签名验证

接口说明:

查询GatePay支持用于静态地址收款的网络和币种

请求参数:

无

响应参数:

字段名 类型 说明
Chains []*FixedChainItem 支持的网络、币种列表

FixedChainItem

字段名 类型 说明
chain string 网络
showChainNameEn string 网络英文名称
currencies string 该网络下支持的币种

请求示例

curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/chains' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727244774062' \
--header 'X-GatePay-Nonce: 6528576972' \
--header 'X-GatePay-Signature: 6bb0a23cf2f397ab4e602e3dc9d04cad59d265fdfe621bbf978409c6c705f86092c6ac5251c0d349dc93e5fbcf9d6ba2e2beae928d3a01ef72ba9ef8581172e5' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc'

响应示例

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "Chains": [
            {
                "chain": "ETH",
                "showChainNameEn": "ETH/ERC20",
                "currencies": [
                    "USDT",
                    "DAI",
                    "ETH",
                    "MATIC",
                    "USDC"
                ]
            },
            {
                "chain": "TRX",
                "showChainNameEn": "Tron/TRC20",
                "currencies": [
                    "USDT"
                ]
            }
        ]
    }
}

# 4.2 创建静态收款地址

  • 数据类型：JSON （content-type：application/json）
  • 请求⽅式：POST
  • 路径Path: /v1/pay/fixedaddress/save
  • 验证⽅式：商户签名验证

接口说明:

按照指定币种和网络，生成静态收款地址

注意: 若channelId + chain已经存在静态收款地址，则会将请求中的currencies和callbackUrl更新到已绑定信息中

请求参数:

字段名 类型 是否必须 说明
channelId string 是 客户名称，只支持字母、数字、下划线和破折号，长度不超过50字节
chain string 是 网络名称
currencies string 是 要在该静态地址上营收的币种，多币种逗号分隔，例如USDT,BTC
callbackUrl string 是 该渠道到账回调地址，长度不超过128字节

响应参数:

字段名 类型 说明
channelId string 客户名称
chain string 网络名称
address string 收款地址
currencies []string 该网络上的收款币种列表
callbackUrl string 该渠道下的收款消息回调地址

请求示例

curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/save' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727602580817' \
--header 'X-GatePay-Nonce: 9167310285' \
--header 'X-GatePay-Signature: a23f55ded2e938fd7b6cd436837b21ec8fd413f3dbd496cffae3bedac3a41c7bf684ca46a25484f8b1607d90313ff46aff2d5b75765ef1d97f51bc63f8e0c139' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--data '{
    "channelId": "smart_shop",
    "chain": "ETH",
    "currencies": "DAI,USDT",
    "callbackUrl": "https://www.abc.com/callback"
}'

响应示例

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "channelId": "smart_shop",
    "chain": "ETH",
    "address": "0x2EBa11a702F1d53c6e2F08278819e26E6e4a63ae",
    "currencies": [
      "DAI",
      "USDT"
    ],
    "callbackUrl": "https://www.abc.com/callback"
  }
}

# 4.3 查询静态收款地址列表

  • 数据类型：JSON （content-type：application/json）
  • 请求⽅式：GET
  • 路径Path: /v1/pay/fixedaddress/list
  • 验证⽅式：商户签名验证

接口说明:

请求参数:

字段名 类型 是否必须 说明
page int 是 从0开始的非负整数，表示页号
count int 是 正整数，每页显示条数，最大100

响应参数:

字段名 类型 说明
total int 总数量
list []*FixedAddressItem 静态收款地址列表

FixedAddressItem

字段名 类型 说明
channelId string 客户名称
chain string 网络
address string 收款地址
currencies []string 该地址上绑定的收款币种
callbackUrl string 到账回调地址
createTime int 创建时间
updateTime int 首次更新时间

请求示例

curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/list?page=0&count=10' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727244774062' \
--header 'X-GatePay-Nonce: 6528576972' \
--header 'X-GatePay-Signature: 6bb0a23cf2f397ab4e602e3dc9d04cad59d265fdfe621bbf978409c6c705f86092c6ac5251c0d349dc93e5fbcf9d6ba2e2beae928d3a01ef72ba9ef8581172e5' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc'

响应示例

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "total": 2,
    "list": [
      {
        "channelId": "smart_shop1",
        "chain": "ETH",
        "address": "0xE2b3fA811f04FD5Ac6559007795D6Fc74365126B",
        "currencies": [
          "USDC"
        ],
        "callbackUrl": "https://www.abc.com/callback",
        "createTime": 1727603135221,
        "updateTime": 1727603135221
      },
      {
        "channelId": "smart_shop",
        "chain": "ETH",
        "address": "0x3FdC81C3f549343a3E0706A382035B7B461C0840",
        "currencies": [
          "DAI",
          "USDT"
        ],
        "callbackUrl": "https://www.abc.com/callback",
        "createTime": 1727603076963,
        "updateTime": 1727603076963
      }
    ]
  }
}

# 4.4 查看静态收款地址详情

  • 数据类型：JSON （content-type：application/json）
  • 请求⽅式：GET
  • 路径Path: /v1/pay/fixedaddress/detail
  • 验证⽅式：商户签名验证

接口说明:

请求参数:

字段名 类型 是否必须 说明
channelId string 是 客户名称
chain string 是 网络

响应参数:

字段名 类型 说明
channelId string 商户绑定静态地址收款时指定的渠道名称
chain string 网络
address string 收款地址
currencies []string 该地址上绑定的收款币种
callbackUrl string 到账回调地址
createTime int 创建时间
updateTime int 首次更新时间

请求示例

curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/detail?channelId=smart_shop&chain=ETH' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727603139811' \
--header 'X-GatePay-Nonce: 2839411632' \
--header 'X-GatePay-Signature: ca46d4a5b7a516faf6d8d770eeba814004733b9660c35f472b36f4cfa045df2df905b0cdcf3a8212a4c39085ed3843fa721b3dd10cbb931dd32fbf4363d36a52' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc'

响应示例

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "channelId": "smart_shop",
    "chain": "ETH",
    "address": "0x5178ff5B10c17282834028E0A79cb18586D44B7C",
    "currencies": [
      "DAI",
      "USDT"
    ],
    "callbackUrl": "https://www.abc.com/callback",
    "createTime": 1727602420837,
    "updateTime": 1727602430742
  }
}

# 4.5 删除静态收款地址

  • 数据类型：JSON （content-type：application/json）
  • 请求⽅式：DELETE
  • 路径Path: /v1/pay/fixedaddress/delete
  • 验证⽅式：商户签名验证

接口说明:

请求参数:

字段名 类型 是否必须 说明
channelId string 是 客户名称
chain string 是 网络

响应参数:

字段名 类型 说明
result string ok表示成功，其它表示失败

请求示例

curl --location --request DELETE 'https://openplatform.gateapi.io/v1/pay/fixedaddress/delete?channelId=smart_shop&chain=ETH' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727603139811' \
--header 'X-GatePay-Nonce: 2839411632' \
--header 'X-GatePay-Signature: ca46d4a5b7a516faf6d8d770eeba814004733b9660c35f472b36f4cfa045df2df905b0cdcf3a8212a4c39085ed3843fa721b3dd10cbb931dd32fbf4363d36a52' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc'

响应示例

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "result": "ok"
  }
}

# 4.6 查询静态收款码账单列表

  • 数据类型：JSON （content-type：application/json）
  • 请求⽅式：GET
  • 路径Path: /v1/pay/fixedaddress/order/query
  • 验证⽅式：商户签名验证

接口说明:

请求参数:

字段名 类型 是否必须 说明
channelId string 是 客户名称
chain string 是 网络
startTime int 是 订单创建时间开始，单位毫秒
endTime int 是 订单创建时间结束，单位毫秒
page int 否 从0开始的非负整数，表示页号
count int 否 正整数，每页显示条数，最大5000
address string 否 收款方Web3地址
fromAddress string 否 付款方Web3地址
txHash string 否 交易hash

响应参数:

字段名 类型 说明
total int 总数量
list []*PaymentDetails 静态收款账单列表

PaymentDetails

字段名 类型 说明
chain string 网络
channelId string 客户名称
currency string 币种
address string 收款方Web3地址
amount string 到账金额
status string 订单状态
txTime int 订单创建时间，单位毫秒
fromAddress string 付款方Web3地址
txHash string 交易hash
transactionId string 交易流水号

请求示例

curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/order/query?page=0&count=10' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727244774062' \
--header 'X-GatePay-Nonce: 6528576972' \
--header 'X-GatePay-Signature: 6bb0a23cf2f397ab4e602e3dc9d04cad59d265fdfe621bbf978409c6c705f86092c6ac5251c0d349dc93e5fbcf9d6ba2e2beae928d3a01ef72ba9ef8581172e5' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc'

响应示例

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "total": 1,
    "details": [
      {
        "chain": "ETH",
        "channelId": "123456",
        "currency": "USDT",
        "address": "0x67C30f439D7734f393c2F4a587B198b8F4086Ccb",
        "amount": "0.62345679",
        "status": "PAID",
        "txTime": 1730960078091,
        "fromAddress": "PAzupoupdSYaYoajDcABEUzigBRzewvzN",
        "txHash": "1820949498602496000930038912",
        "transactionId": "343656213785650801"
      }
    ]
  }
}

# 5. 其它

Last Updated: 6/3/2025, 1:43:31 AM