• Python
  • Golang
  • Java

# 1. Introduction to the Client Management Function

Solutions provided by Gate Pay for gateway merchants.

Gateway merchants can maintain their own clients and distinguish transactions by client when using GatePay's collection and crediting functions.

# 2. API List

# 2.1 Add Client

Users create clients and record information through this interface. The name of a client is required and must be unique under the same merchant; other attributes are not required. If you need to save a wallet address, you need to confirm the network; if not, the network can be left blank. Spare fields are set by merchants according to actual business scenarios. You can use a spare field to save certain attribute of your clients, e.g., country/region/business type.

  • Data Type: JSON (content-type: application/json)
  • Request Method: POST
  • Path: /v1/pay/channelmanage/save
  • Validation Method: Signature verification
  • Request Body Content:
Field Name Type Required Description
merchantChannelList Channel Type Yes Client list,currently only supports adding one client record each time

Channel type

Field Name Type Required Description
channelId string Yes Client Name, the unique identifier of a client's identity entered by the merchant. It's unique under the same merchant and cannot be edited
desc string No Client description, used for remarks
channelType string No Client type; optional values: 0 or 1 (0 = Individual; 1 = Corporate)
address string No Save the client's collection address; used for client withdrawals
chain string No Save the client's collection network; used for client withdrawals. After getting the list of supported currencies, use the interface (/v1/pay/address/chains) to acquire the currency's chain network information
customFields Custom Type No Custom field list

Custom Type

Field Name Type Required Description
code string No Custom field, used to link the code of the spare field for client attribute settings on the merchant's dashboard
name string Yes Custom field, name of the spare field
value string Yes Custom field, value of the spare field

Response Fields:

Field Name Type Required Description
status string Yes SUCCESS or FAIL
code string Yes Error code
errorMessage string No Error message

Request Example:

curl --location 'https://openplatform.gateapi.io/v1/pay/channelmanage/save' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--data '{
    "merchantChannelList": [
        {
            "channelId": "test",
            "desc": "remarks",
            "channelType": "0",
            "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
            "chain": "ETH",
            "customFields": [
                {
                    "code": "customCode",
                    "name": "customName",
                    "value": "customValue"
                }
            ]
        }
    ]
}'

Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": ""
}

# 2.2 Query Client

Query information about the current merchant's client list.

  • Data Type: JSON (content-type: application/json)
  • Request Method: GET
  • Path: /v1/pay/channelmanage/list
  • Validation Method: Signature verification
  • Request Body Content:
Field Name Type Required Description
channelId string No Client Name; fuzzy query
desc string No Client description; fuzzy query
channelType string No Client type; optional values: 0 or 1 (0 = Individual; 1 = Corporate)
page int Yes No. of the start page
count int Yes Number of records per page

Response Fields:

Field Name Type Description
status string SUCCESS or FAIL
code string Error code
errorMessage string Error message
data Data Type Error message

Data Type

Field Name Type Description
total int64 Total number of records
merchantChannelList Channel Type Client list

Channel type

Field Name Type Description
channelId string Client Name
desc string Client description
channelType string Client type
address string The client's collection address
chain string The client's collection network
customFields Custom Type Custom field list

Custom Type

Field Name Type Description
code string Custom field
name string Custom field
value string Custom field

Request Example:

curl --location 'https://openplatform.gateapi.io/v1/pay/channelmanage/list' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--data '{
    "page": 1,
    "count":10
}'

Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
  "data": {
    "total": 217,
    "merchantChannelList": [
      {
        "channelId": "test",
        "desc": "remarks",
        "channelType": "0",
        "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
        "chain": "ETH",
        "createTime": "1735568326554",
        "updateTime": "1735568326554",
        "customFields": [
          {
            "code": "customCode",
            "name": "customName",
            "value": "customValue"
          }
        ]
      }
    ]
  }
}

# 2.3 Edit Client

Users edit clients and record information through this interface. The name of a client is required and must be unique under the same merchant; other attributes are not required. If you need to save a wallet address, you need to confirm the network; if not, the network can be left blank. Spare fields are set by merchants according to actual business scenarios. You can use a spare field to save certain attribute of your clients, e.g., country/region/business type.

  • Data Type: JSON (content-type: application/json)
  • Request Method: PUT
  • Path: /v1/pay/channelmanage/update
  • Validation Method: Signature verification
  • Request Body Content:
Field Name Type Required Description
merchantChannelList Channel Type Yes Client list,currently only supports editing one client record each time

Channel type

Field Name Type Required Description
channelId string Yes Client Name, the unique identifier of a client's identity entered by the merchant. It's unique under the same merchant and cannot be edited
desc string No Client description, used for remarks
channelType string No Client type; optional values: 0 or 1 (0 = Individual; 1 = Corporate)
address string No Save the client's collection address; used for client withdrawals
chain string No Save the client's collection network; used for client withdrawals. After getting the list of supported currencies, use the interface (/v1/pay/address/chains) to acquire the currency's chain network information
customFields Custom Type No Custom field list

Custom Type

Field Name Type Required Description
code string No Custom field, used to link the code of the spare field for client attribute settings on the merchant's dashboard
name string Yes Custom field, name of the spare field
value string Yes Custom field, value of the spare field

Response Fields:

Field Name Type Required Description
status string Yes SUCCESS or FAIL
code string Yes Error code
errorMessage string No Error message

Request Example:

curl --location 'https://openplatform.gateapi.io/v1/pay/channelmanage/update' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--data '{
    "merchantChannelList": [
        {
            "channelId": "test",
            "desc": "remarks",
            "channelType": "0",
            "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
            "chain": "ETH",
            "customFields": [
                {
                    "code": "customCode",
                    "name": "customName",
                    "value": "customValue"
                }
            ]
        }
    ]
}'

Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": ""
}

# 2.4 Delete Client

Delete information about a client.

  • Data Type: JSON (content-type: application/json)
  • Request Method: DELETE
  • Path: /v1/pay/channelmanage/delete
  • Validation Method: Signature verification
  • Request Body Content:
Field Name Type Required Description
channelId string Yes Client Name

Response Fields:

Field Name Type Required Description
status string Yes SUCCESS or FAIL
code string Yes Error code
errorMessage string No Error message

Request Example:

curl --location 'https://openplatform.gateapi.io/v1/pay/channelmanage/delete' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--data '{
    "channelId": "test"
}'

Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": ""
}

# 3. Steps for Merchants to Access the Cashier

# 3.1 Gate Pay's Preparation for Accessing

Please refer to Gate Pay Access Preparation

# 3.2 Get Chain Information for Address Payment

To call the add client interface (/v1/pay/channelmanage/save), merchants need to provide the chain and chain network information. The process is as follows.

  1. Use the interface (/v1/pay/address/currencies) to query the list of supported currencies for the address payment.
  2. Then use the interface (/v1/pay/address/chains) to acquire the currency's chain network information.

# 4. FAQ

# Q: Why does the prompt say the client name's returned parameter is illegal?

A: The client name should be no longer than 50 characters. It supports Chinese characters, numbers, uppercase and lowercase letters, and special characters such as "_", "/", "|", and "-". Spaces are not allowed.

# Q: Why did I fail to delete a client?

A: Because the current client is being used by payment products. You need to ensure payment products (address payment and static collection QR codes) are not using this client (Delete the corresponding collection QR code or wait for it to become expired).

# 5. Error Codes

Error Code Description Solution
400001 Request parameter format error Check request data parameters and format
400002 Signature verification failed Check if the merchant's signature is correct
400003 Request timestamp timed out Check the timestamp field in the request header
5502921 [] exceeds the length limit Check the request [field name] length
5502922 [] Invalid data. Please refer to the instructions Check request [field name] data format is incorrect, please refer to the filling instructions
5502923 Client is required Check if the request field [merchantChannelList] is empty
5502924 Client Name is required Check if the request field [channelId] is empty
5502925 Client Name only supports Chinese characters, letters, numbers, underscores, and hyphens. Check whether the request field [channelId] is correct
5502926 Client type can only be 0 or 1 Check the request field [channelType]
5502927 Client Name does not exist. Check the request field [channelId]
5502928 Client Name already exists Check the request field [channelId]
5502929 Failed to delete the client because it is currently linked to payment products. Please remove the associated payment products first. Check the request field [channelId]
5502930 Abnormal data Check whether the request field is legal
Last Updated: 5/23/2025, 12:54:07 PM