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

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

Response Fields:

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

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

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

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

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

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

Response Fields:

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

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

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

Response Fields:

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

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