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. 其它