Python
Golang
Java

# changelog

# v1.0.0

2024-09-25
Static Address Collection Integration Document - Initial Version

# 1. Function Overview

The Static Address Collection method allows users to transact with Gate merchants using any wallet asset without the need for a Gate account.

Unlike the existing “Address Payment”, where a unique address is generated for each transaction, the Static Address Collection assigns a predefined set of addresses to the merchant.

Users transfer funds to these static addresses, Gate processes the payment, settles the funds into the merchant’s Gate payment account, and relays the payment details to the merchant.

# 2. Static Collection Code

# 2.1 Security Verification

Refer to API Signature for security verification

# 2.2 Sequence Diagram

# 3. Message Notification

# 3.1 Scenarios for Sending Messages to Merchants

When the merchant’s bound collection address receives funds, and the collection network and received currency are within the merchant’s revenue scope.

# 3.2 Static Address Collection Message Enumeration Values

bizType

Value	Description
`PAY_FIXED_ADDRESS`	It is a notification type for static address collection

bizStatus

Value	Description
`PAY_SUCCESS`	Payment successful and funds credited
`PAY_BLOCK`	Gate successfully received the payment, but the funds are flagged as risky and will not be credited

# 3.3 Static Address Collction Message Fields

Field Name	Type	Description
`bizType`	`string`	Type of message notification
`bizId`	`string`	Order ID
`data`	`string`	JSON-encoded `dataType`

dataType

Field Name	Type	Description
`channelId`	`string`	Merchant channel ID, supports only letters, numbers, underscores, and hyphens, with a maximum length of 50 bytes
`currency`	`string`	Order currency
`orderAmount`	`string`	Order amount
`createTime`	`int`	Order creation time
`transactionId`	`string`	Transaction ID
`transactionTime`	`string`	Order filled time
`chain`	`string`	Network name
`address`	`string`	Collection address
`amount`	`string`	Collection amount

Message Structure Example

{
    "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\"}"
}

After receiving an asynchronous callback message, the merchant must respond according to the structure below, and returnCode is SUCCESS, otherwise Gate will assume that no success notification was provided. The response example is as follows:

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

# 4. Static Collection Address API List

# 4.1 Query Supported Networks and Currencies

Data Type: JSON （content-type：application/json）
Request Method: GET
Path: /v1/pay/fixedaddress/chains
Validation Method: Merchant signature verification

Interface Description:

Queries the networks and currencies supported by GatePay for static address collection.

Request Parameters:

None

Response Parameters:

Field Name	Type	Description
`Chains`	`[]*FixedChainItem`	List of supported networks and currencies

FixedChainItem

Field Name	Type	Description
`chain`	`string`	Network
`showChainNameEn`	`string`	Network English name
`currencies`	`string`	Currencies supported under this network

Request Example

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'

Response Example

{
    "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 Create Static Collection Address

Data Type: JSON （content-type：application/json）
Request Method: POST
Path: /v1/pay/fixedaddress/save
Validation Method: Merchant signature verification

Interface Description:

Generates a static collection address based on the specified currency and network.

Note: If a static collection address already exists forchannelId + chain, the currencies and callbackUrl in the request will update the existing bound information.

Request Parameters:

Field Name	Type	Required	Description
`channelId`	`string`	Yes	Merchant channel ID, supports only letters, numbers, underscores, and hyphens, with a maximum length of 50 bytes
`chain`	`string`	Yes	Network name
`currencies`	`string`	Yes	Currencies to be earned at this static address, separated by commas (e.g., `USDT,BTC`
`callbackUrl`	`string`	Yes	Callback URL for this channel, with a maximum length of 128 bytes

Response Parameters:

Field Name	Type	Description
`channelId`	`string`	Merchant channel ID
`chain`	`string`	Network name
`address`	`string`	Collection address
`currencies`	`[]string`	List of supported currencies for this network
`callbackUrl`	`string`	Callback URL for collection notifications

Request Example

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"
}'

Response Example

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

# 4.3 Query Static Collection Address List

Data Type: JSON （content-type：application/json）
Request Method: GET
Path: /v1/pay/fixedaddress/list
Validation Method: Merchant signature verification

Interface Description:

Queries the list of generated and valid static collection addresses.

Request Parameters:

Field Name	Type	Required	Description
`page`	`int`	Yes	A non-negative integer starting from 0, indicating the page number
`count`	`int`	Yes	A positive integer representing the number of entries displayed per page, with a maximum of 100

Response Parameters:

Field Name	Type	Description
`total`	`int`	Total amount
`list`	`[]*FixedAddressItem`	Fixed collection address list

FixedAddressItem

Field Name	Type	Description
`channelId`	`string`	Merchant channel ID
`chain`	`string`	Network
`address`	`string`	Collection address
`currencies`	`[]string`	Currencies bound to this address
`callbackUrl`	`string`	Callback URL for collection notifications
`createTime`	`int`	Creation time
`updateTime`	`int`	First update time

Request Example

curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/list?page=0&amp;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'

Response Example

{
  "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 View Static Collection Address Details

Data Type: JSON （content-type：application/json）
Request Method: GET
Path: /v1/pay/fixedaddress/detail
Validation Method: Merchant signature verification

Interface Description:

Views the details of an already generated and valid static collection address.

Request Parameters:

Field Name	Type	Required	Description
`channelId`	`string`	Yes	Merchant channel ID
`chain`	`string`	Yes	Network

Response Parameters:

Field Name	Type	Description
`channelId`	`string`	The channel ID specified by the merchant when binding the static collection address
`chain`	`string`	Network
`address`	`string`	Collection address
`currencies`	`[]string`	Currencies bound to this address
`callbackUrl`	`string`	Callback URL for collection notifications
`createTime`	`int`	Creation time
`updateTime`	`int`	First update time

Request Example

curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/detail?channelId=smart_shop&amp;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'

Response Example

{
  "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 Delete Static Collection Address

Data Type: JSON （content-type：application/json）
Request Method: DELETE
Path: /v1/pay/fixedaddress/delete
Validation Method: Merchant signature verification

Interface Description:

Deletes an already generated and valid static collection address.

Request Parameters:

Field Name	Type	Required	Description
`channelId`	`string`	Yes	Merchant channel ID
`chain`	`string`	Yes	Network

Response Parameters:

Field Name	Type	Description
`result`	`string`	`ok` indicates success; anything else indicates failure

# 4.6 Query Static Address Order List

Data Type:JSON （content-type：application/json）
Request Method:GET
Path: /v1/pay/fixedaddress/order/query
Validation Method: Merchant signature verification

Interface Description:

Request Parameters:

Field Name	Type	Required	Description
`channelId`	`string`	Yes	Merchant channel name
`chain`	`string`	Yes	Network name
`startTime`	`int`	Yes	Order creation time start in milliseconds
`endTime`	`int`	Yes	Order creation time end in milliseconds
`page`	`int`	Yes	A non-negative integer starting from 0, indicating the page number
`count`	`int`	Yes	A positive integer representing the number of entries displayed per page, with a maximum of 100
`address`	`string`	No	Collection address
`fromAddress`	`string`	No	Payer address
`txHash`	`string`	No	Transaction Hash

Response Parameters:

Field Name	Type	Description
`total`	`int`	Total amount
`list`	`[]*PaymentDetails`	Detail list

PaymentDetails

Field Name	Type	Description
`chain`	`string`	Network name
`channelId`	`string`	Merchant channel name
`currency`	`string`	Currency
`address`	`string`	Collection address
`amount`	`string`	Income amount
`status`	`string`	Order status
`txTime`	`int`	Order creation time
`fromAddress`	`string`	Payer address
`txHash`	`string`	Transaction Hash
`transactionId`	`string`	Transaction ID

Request Example

curl --location --request DELETE 'https://openplatform.gateapi.io/v1/pay/fixedaddress/delete?channelId=smart_shop&amp;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'

Response Example

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

Request Example

curl --location 'https://openplatform.gateapi.io/v1/pay/fixedaddress/order/query?page=0&amp;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'

Response Example

{
  "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. Others

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