1. 客户管理功能介绍

Gate Pay提供的网关商户解决方案。

网关商户可以维护自己的客户，在使用GatePay收款和下发功能时可通过客户名称来区分交易。

2.API列表

2.1 新增客户

用户通过该接口创建客户记录信息。 客户名称必填且商户下唯一，其余属性非必填。 如果需要保存钱包地址，则需要确定网络，如果不需要保存钱包地址则均可为空。 备用字段为商户根据实际业务场景来设定，可以选择用于保存客户的某个属性，如“国家/地区/业务类型”等。

• 数据类型：JSON （content-type： application/json）
• 请求方式：POST
• Path: /v1/pay/channelmanage/save
• 验证方式：签名验证
• 请求体内容:

字段名	类型	是否必须	说明
merchantChannelList	Channel Type	是	客户列表，当前仅支持每次新增一个客户记录

Channel type

字段名	类型	是否必须	说明
channelId	string	是	客户名称，是客户身份的唯一识别码，由商户自己录入，在商户下唯一且无法修改
desc	string	否	客户描述，用于备注
channelType	string	否	客户类型，可选值：0或1(0=个人；1=企业)
address	string	否	保存客户的收款地址，用于客户提现
chain	string	否	保存客户的收款网络，用于客户提现，在获取到支持币种列表后，再使用接口(/v1/pay/address/chains)获取币种链网络信息
customFields	Custom Type	否	自定义字段列表

Custom Type

字段名	类型	是否必须	说明
code	string	否	自定义字段code，用于关联商户后台客户属性设置预留字段code
name	string	是	自定义字段name，作为预留字段名称
value	string	是	自定义字段value ，作为预留字段值

请求示例:

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": "备注",
            "channelType": "0",
            "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
            "chain": "ETH",
            "customFields": [
                {
                    "code": "customCode",
                    "name": "customName",
                    "value": "customValue"
                }
            ]
        }
    ]
}'

响应：

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

响应字段：

字段名	类型	是否必须	说明
status	string	是	SUCCESS 或者 FAIL
code	string	是	出错代码
errorMessage	string	否	错误信息

2.2 查询客户

查询当前商户的客户列表信息。

• 数据类型：JSON （content-type： application/json）
• 请求方式：GET
• Path: /v1/pay/channelmanage/list
• 验证方式：签名验证
• 请求体内容:

字段名	类型	是否必须	说明
channelId	string	否	客户名称，模糊搜索
desc	string	否	客户描述，模糊搜索
channelType	string	否	客户类型，可选值：0或1(0=个人；1=企业)
page	int	是	开始页编号
count	int	是	单页记录数

请求示例:

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

响应：

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

响应字段：

字段名	类型	说明
status	string	SUCCESS 或者 FAIL
code	string	出错代码
errorMessage	string	错误信息
data	Data Type	错误信息

Data Type

字段名	类型	说明
total	int64	总记录数
merchantChannelList	Channel Type	客户列表

Channel type

字段名	类型	说明
channelId	string	客户名称
desc	string	客户描述
channelType	string	客户类型
address	string	客户的收款地址
chain	string	客户的收款网络
customFields	Custom Type	自定义字段列表

Custom Type

字段名	类型	说明
code	string	自定义字段code
name	string	自定义字段name
value	string	自定义字段value

2.3 修改客户

用户通过该接口修改客户记录信息。 客户名称必填且商户下唯一，其余属性非必填。 如果需要保存钱包地址，则需要确定网络，如果不需要保存钱包地址则均可为空。 备用字段为商户根据实际业务场景来设定，可以选择用于保存客户的某个属性，如“国家/地区/业务类型”等。

• 数据类型：JSON （content-type： application/json）
• 请求方式：PUT
• Path: /v1/pay/channelmanage/update
• 验证方式：签名验证
• 请求体内容:

字段名	类型	是否必须	说明
merchantChannelList	Channel Type	是	客户列表，当前仅支持每次修改一个客户记录

Channel type

字段名	类型	是否必须	说明
channelId	string	是	客户名称，是客户身份的唯一识别码，由商户自己录入，在商户下唯一且无法修改
desc	string	否	客户描述，用于备注
channelType	string	否	客户类型，可选值：0或1(0=个人；1=企业)
address	string	否	保存客户的收款地址，用于客户提现
chain	string	否	保存客户的收款网络，用于客户提现，在获取到支持币种列表后，再使用接口(/v1/pay/address/chains)获取币种链网络信息
customFields	Custom Type	否	自定义字段列表

Custom Type

字段名	类型	是否必须	说明
code	string	否	自定义字段code，用于关联商户后台客户属性设置预留字段code
name	string	是	自定义字段name，作为预留字段名称
value	string	是	自定义字段value ，作为预留字段值

请求示例:

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": "备注",
            "channelType": "0",
            "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
            "chain": "ETH",
            "customFields": [
                {
                    "code": "customCode",
                    "name": "customName",
                    "value": "customValue"
                }
            ]
        }
    ]
}'

响应：

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

响应字段：

字段名	类型	是否必须	说明
status	string	是	SUCCESS 或者 FAIL
code	string	是	出错代码
errorMessage	string	否	错误信息

2.4 删除客户

删除客户信息。

• 数据类型：JSON （content-type： application/json）
• 请求方式：DELETE
• Path: /v1/pay/channelmanage/delete
• 验证方式：签名验证
• 请求体内容:

字段名	类型	是否必须	说明
channelId	string	是	客户名称

请求示例:

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

响应：

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

响应字段：

字段名	类型	是否必须	说明
status	string	是	SUCCESS 或者 FAIL
code	string	是	出错代码
errorMessage	string	否	错误信息

3.商户接入客户管理步骤

3.1 Gate Pay接入准备

请参考Gate Pay接入准备文档

3.2 新增客户

商户在调用新增客户接口(/v1/pay/channelmanage/save)时，需要传入链网络信息,该信息获取接口步骤如下。

1. 使用接口(/v1/pay/address/currencies)查询支持的地址支付币种列表。
2. 在获取到支持币种列表后，在使用接口(/v1/pay/address/chains)获取币种链网络信息。

4. 常见问题

Q:为什么提示客户名称返回参数非法

A: 客户名称长度50个字符，允许输入中文、数字和字母大小写，允许"_","/","|","-"等特殊字符，不允许空格。

Q:为什么客户删除失败

A:因为当前客户已被收款产品使用，需要确保收款产品（地址支付和静态收款码）没有在使用该客户。（删除对应的收款码或等收款码变为已过期）。

5. 错误码

错误码	描述	解决方案
400001	请求参数格式错误	检查请求数据格式
400002	签名校验失败	检查请求数据格式
400003	请求时间戳超时	检查商户签名是否正确
5502921	【字段名】长度超限制	检查请求【字段名】长度
5502922	【字段名】数据不正确，请参考填写说明	检查请求【字段名】数据格式不正确，请参考填写说明
5502923	客户不能为空	检查请求[merchantChannelList]是否为空
5502924	客户名称不能为空	检查请求字段[channelId]
5502925	客户名称只支持中文、字母、数字、下划线和破折号	检查请求字段[channelId]
5502926	客户类型只能为0或1	检查请求字段【客户类型】
5502927	客户名称不存在	检查请求字段[channelId]
5502928	客户名称已存在	检查请求字段[channelId]
5502929	客户删除失败，当前客户已被收款产品使用，请先删除关联的收款产品	检查请求字段[channelId]
5502930	存在异常数据	检查请求字段是否合法