静态地址收款方式目标是支持用户在没有Gate账户前提下,可以使用任意钱包资产与Gate商户进行交易
区别于现有"地址支付",静态收款地址不会为每一笔账单分配一个不同的地址,而是商户事先申请一定数
量的静态地址,用户向静态地址转账,Gate生成支付账单,结算至商户Gate支付账户,并向商户推送用
户支付信息
字段名 | 类型 | 说明 |
---|---|---|
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": ""
}
JSON (content-type:application/json)
GET
/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"
]
}
]
}
}
JSON (content-type:application/json)
POST
/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"
}
}
JSON (content-type:application/json)
GET
/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
}
]
}
}
JSON (content-type:application/json)
GET
/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
}
}
JSON (content-type:application/json)
DELETE
/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"
}
}
JSON (content-type:application/json)
GET
/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"
}
]
}
}