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&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&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

Request Example

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'

Response Example

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

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

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