1. 功能介绍

通过 GatePay 机构 API，机构可以在客户同意的前提下，将自己的客户（商户、创作者、用户等）接入 GatePay，并在一个统一的账户体系内管理这些客户的资金和交易。整体上，机构先开立自己的 GatePay 机构账户，再通过 API 为每个客户在 GatePay 中创建对应账户，该账户在体系内作为“机构账户名下的子账户（sub-account）”存在，资金归属客户，账户归属机构的管理域。

基于这一账户模型，机构可以在自身系统中，以子账户的名义发起和管理各类业务操作，包括但不限于：

• 收单：以子账户为收款方创建订单，让终端用户直接向该子账户付款；
• 闪兑 / 兑换：以子账户为主体在 GatePay 内部进行币种或资产间转换；
• 付款 / 提现：以子账户为付款方发起对外或对内的付款、结算、提现；
• 查询：查询子账户的余额、账务流水、订单列表及订单状态等信息；

同时，GatePay 提供 charge 和 transfer 两类资金接口，用于在 GatePay 账户体系内部进行资金往来：

• 在「机构账户 ↔ 子账户」之间实现平台抽成、服务费扣收、定期结算和资金归集；
• 在「子账户 ↔ 子账户」之间实现多主体、多业务线的内部划转和分账；

机构无需自建底层账务系统，即可依托 GatePay 搭建符合自身业务规则的分润、结算与资金管理逻辑。

为区分一次请求是操作机构自己的账户，还是代某个子账户操作，API 约定使用一个逻辑参数 X-GatePay-On-Behalf-Of：

• 当请求中携带 X-GatePay-On-Behalf-Of = 子账户ID 时，本次操作的业务主体视为该子账户，收单、闪兑、付款、查询等行为都会体现在该子账户名下；
• 当请求中携带 X-GatePay-On-Behalf-Of 为机构自身商户ID时，默认视为针对机构自身的 GatePay 机构账户进行操作，更适合用于机构层面的资金管理、总账户层面的收付与归集等场景。

以下是交互时序图

2. API 接口

2.1 账户

2.1.1 创建子账户

• API描述：以机构账户为主体，为客户创建一个新的子账户并登记账户持有人信息

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/v1/accounts/create

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
request_id	string	是	请求方唯一ID
customer_id	string	是	平台侧客户 ID
display_name	string	是	子账户展示名
account_holder	AccountHolder	是	账户持有人（主体）信息
metadata	map<string, object>	否	附加键值对

AccountHolder:

字段名	类型	是否必须	说明
entity_country	string	是	主体所在国家ISO代码，完整列表可参考 ISO 官方在线浏览平台或各类公开的 ISO 3166-1 alpha-2 对照表（例如 IBAN 官网提供的国家代码列表: https://www.iban.com/country-codes ）
entity_type	string	是	主体类型 个人-INDIVIDUAL 企业-BUSINESS
entity_name	string	是	主体名称（个人姓名/企业法定名称）
entity_id_type	string	是	证件类型，详见证件类型枚举
entity_id_number	string	是	证件号码
entity_id_expiry	EntityIdExpiry	是	证件有效期
dob	Dob	否	出生日期，当entity_type为INDIVIDUAL必填
business_registration	BusinessRegistration	否	企业注册信息，当entity_type为INDIVIDUAL可填
address	Address	是	主体所在地址
merchant_category	string	是	商户大类，详见商户大类枚举
website	string	否	企业网站
user_agreement	bool	是	用户是否签署协议
ubo_list	list<Ubo>	否	法人信息/UBO信息 当 entity_type 为 BUSINESS，必填

EntityIdExpiry:

字段名	类型	是否必须	说明
valid_from	int64	是	生效日期毫秒时间戳
valid_to	int64	否	失效日期毫秒时间戳

Dob:

字段名	类型	是否必须	说明
year	int	是	四位年份
month	int	是	月份，1-12
day	int	是	日，1-31

BusinessRegistration:

字段名	类型	是否必须	说明
reg_number	string	否	注册号
reg_country	string	否	注册国家
established_at	int64	否	成立日期

Address:

字段名	类型	是否必须	说明
line1	string	是	地址行1
line2	string	否	地址行2
line3	string	否	地址行3
country	string	是	国家代码
city	string	否	城市
state	string	否	省/州
postal_code	string	否	邮编

Ubo:

字段名	类型	是否必须	说明
country	string	是	所在国家ISO代码
full_name	string	是	个人姓名
dob	Dob	是	出生日期
id_type	string	是	证件类型，请填写个人证件类型
id_number	string	是	证件号码
id_expiry	EntityIdExpiry	是	证件有效期
relationship	Relationship	是	人员和子商户的关系属性

Relationship：

字段名	类型	是否必须	说明
is_representative	boolean	否	是否为法定代表人
is_owner	boolean	否	是否为最终受益人
percent_ownership	decimal	否	is_owner 为 ture 时，必填；填写持股比例数字，示例：30.01

证件类型枚举：

枚举值	说明	适用主体
PASSPORT	护照	个人
NATIONAL_ID	国家身份证/居民身份证	个人
DRIVING_LICENSE	驾驶证/驾照	个人
BUSINESS_LICENSE	营业执照 / 商业登记证	企业
CERTIFICATE_OF_INCORPORATION	公司注册证明书	企业

商户大类枚举：

枚举值	中文说明	典型示例
GENERAL_RETAIL	一般零售 / 综合电商	百货、综合电商平台、杂货零售、日用品网店
SUPERMARKET_CONVENIENCE	超市 / 便利店	连锁超市、社区便利店、生鲜连锁
FASHION_AND_ACCESSORIES	服饰 / 鞋帽 / 配饰	服装店、鞋店、箱包店、饰品店
FOOD_AND_BEVERAGE	餐饮 / 外卖	正餐、快餐、咖啡店、甜品店、酒吧、外卖平台
DIGITAL_CONTENT_AND_SAAS	数字内容 / SaaS 服务	线上订阅、云服务、在线工具、音视频订阅、生产力软件
GAMING_AND_ENTERTAINMENT	游戏 / 文娱	网游、手游充值、游戏平台、直播打赏、在线视频娱乐
TRAVEL_AND_TICKETING	机酒 / 票务 / 旅行服务	机票、酒店预订、火车/大巴票、旅行社、OTA
RIDE_HAILING_AND_TRANSPORT	网约车 / 出行 / 交通	网约车平台、共享单车/电动车、停车缴费、公交通票
HOSPITALITY_AND_LEISURE	住宿 / 休闲 / 文旅	酒店、民宿、景区门票、度假村、游乐园
EDUCATION	教育 / 培训	K12 教育、职业培训、线上课程平台
HEALTHCARE_AND_WELLNESS	医疗 / 健康 / 美业	医疗机构、药房、体检中心、健身房、美容美发
FINANCIAL_SERVICES	金融服务	支付机构、理财平台、保险、证券/经纪服务（非虚拟资产）
CRYPTO_AND_WEB3	虚拟资产 / Web3 / Crypto	交易所、钱包服务商、DeFi 入口、NFT 平台、链上支付类商户
UTILITIES_AND_BILLS	生活缴费 / 公用事业	水电煤、宽带、手机话费、物业费
CHARITY_AND_NONPROFIT	慈善 / 公益组织	慈善机构、非营利组织、募捐平台
OTHER	其他未分类行业	无法归入上述任一大类的商户

• 响应内容

字段名	类型	说明
request_id	string	创建申请单号
status	string	账户状态 初始态-INIT 处理中-PENDING 已创建-ACTIVE 创建失败-FAIL
created	string	创建时间（毫秒）
customer_id	string	平台侧客户 ID
display_name	string	展示名
account_holder	AccountHolder	账户持有人（主体）信息
metadata	map<string, object>	附加键值对

CURL 请求

curl --location --request POST 'https://openplatform.gateapi.io/merchant/open/institution/v1/accounts/create' \
--header 'X-GatePay-Certificate-ClientId: 4186d0c6-6a35-55a9-8dc6-5312769dbff8' \
--header 'X-GatePay-Signature: 672d5650dcc9bb22ebf25fa16c28d03c0e159d742a9176d4340a5da326d75dc8a2ec24c97fa6fc5d1533dd6e968863747e1d86a45e562cbe899f9ed7e9ca7f77' \
--header 'X-GatePay-Timestamp: 1672905655498' \
--header 'X-GatePay-Nonce: 9578' \
--header 'Content-Type: application/json' \
--data-raw '{
   "request_id":"9962354390165",
   "customer_id":"2271514627301",
   "display_name":"机构子账户5563803339",
   "account_holder":{
      "entity_name":"山东",
      "entity_country":"AF",
      "ubo_list":[
         {
            "country":"AF",
            "full_name":"测试名字778",
            "dob":{
               "year":2026,
               "month":3,
               "day":3
            },
            "id_type":"DRIVING_LICENSE",
            "id_number":"130",
            "id_expiry":{
               "valid_from":1773135745000,
               "valid_to":1873135745000
            },
            "relationship":{
               "is_representative":false,
               "is_owner":false,
               "percent_ownership":"30"
            }
         }
      ],
      "entity_type":"BUSINESS",
      "entity_id_type":"BUSINESS_LICENSE",
      "entity_id_number":"abcd1234",
      "dob":{
         "year":1998,
         "month":12,
         "day":10
      },
      "address":{
         "line1":"line1",
         "country":"country"
      },
      "entity_id_expiry":{
         "valid_from":1773136302158,
         "valid_to":1773172302158
      },
      "merchant_category":"GENERAL_RETAIL",
      "user_agreement":true
   },
   "metadata":{
      "k1":"自动化巡检",
      "k2":123
   }
}'

响应:

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "request_id": "35778162074976257",
    "status": "INIT",
    "created": 1764139242707,
    "display_name": "my test",
    "customer_id": "1234",
    "account_holder": {
      "entity_country": "AF",
      "entity_type": "BUSINESS",
      "entity_name": null,
      "entity_id_type": "BUSINESS_LICENSE",
      "entity_id_number": "abcd1234",
      "entity_id_expiry": {
        "valid_from": 1763538010509,
        "valid_to": null
      },
      "dob": null,
      "business_registration": null,
      "address": null,
      "merchant_category": "GENERAL_RETAIL",
      "website": null,
      "user_agreement": true
    },
    "metadata": null
  }
}

2.1.2 更新子账户

• API描述：更新子账户资料及持有人信息

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 路径Path: /merchant/open/institution/v1/accounts/update

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
display_name	string	否	子账户展示名
account_holder	AccountHolder	否	账户持有人（主体）信息（覆盖更新）
metadata	map<string, object>	否	附加键值对

• 响应内容

字段名	类型	说明
account_id	string	子账户 ID
status	string	账户状态 初始态-INIT 处理中-PENDING 已创建-ACTIVE 创建失败-FAIL
updated	string	更新时间（毫秒）
customer_id	string	平台侧客户 ID
display_name	string	展示名
account_holder	AccountHolder	账户持有人（主体）信息
metadata	map<string, object>	附加键值对

CURL 请求

curl --location --request POST 'https://openplatform.gateapi.io/merchant/open/institution/v1/accounts/update' \
--header 'X-GatePay-Certificate-ClientId: 4186d0c6-6a35-55a9-8dc6-5312769dbff8' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'X-GatePay-Signature: 672d5650dcc9bb22ebf25fa16c28d03c0e159d742a9176d4340a5da326d75dc8a2ec24c97fa6fc5d1533dd6e968863747e1d86a45e562cbe899f9ed7e9ca7f77' \
--header 'X-GatePay-Timestamp: 1672905655498' \
--header 'X-GatePay-Nonce: 9578' \
--header 'Content-Type: application/json' \
--data-raw '{
    "display_name": "new name",
    "account_holder":{
      "entity_name":"山东",
      "entity_country":"AF",
      "ubo_list":[
         {
            "country":"AF",
            "full_name":"测试名字778",
            "dob":{
               "year":2026,
               "month":3,
               "day":3
            },
            "id_type":"DRIVING_LICENSE",
            "id_number":"130",
            "id_expiry":{
               "valid_from":1773135745000,
               "valid_to":1873135745000
            },
            "relationship":{
               "is_representative":false,
               "is_owner":false,
               "percent_ownership":"30"
            }
         }
      ],
      "entity_type":"BUSINESS",
      "entity_id_type":"BUSINESS_LICENSE",
      "entity_id_number":"abcd1234",
      "dob":{
         "year":1998,
         "month":12,
         "day":10
      },
      "address":{
         "line1":"line1",
         "country":"country"
      },
      "entity_id_expiry":{
         "valid_from":1773136302158,
         "valid_to":1773172302158
      },
      "merchant_category":"GENERAL_RETAIL",
      "user_agreement":true
   }
}'

响应:

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "status": "ACTIVE",
    "updated": 1764141615061,
    "display_name": "new name",
    "customer_id": "1234",
    "account_id": "2124538349",
    "account_holder": {
      "entity_country": "AF",
      "entity_type": "BUSINESS",
      "entity_name": null,
      "entity_id_type": "BUSINESS_LICENSE",
      "entity_id_number": "abcd1234",
      "entity_id_expiry": {
        "valid_from": 1763538010509,
        "valid_to": null
      },
      "dob": null,
      "business_registration": null,
      "address": null,
      "merchant_category": "GENERAL_RETAIL",
      "website": null,
      "user_agreement": true
    },
    "metadata": null
  }
}

2.1.3 查询子账户

• API描述：查询子账户详情

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/v1/accounts/query

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
request_id	string	否	创建申请单号
account_id	string	否	子账户 ID

• 响应内容

字段名	类型	说明
request_id	string	创建申请单号
account_id	string	子账户 ID
customer_id	string	平台侧客户 ID
display_name	string	展示名
status	string	账户状态 初始态-INIT 处理中-PENDING 已创建-ACTIVE 创建失败-FAIL
created	int64	创建时间（毫秒）
updated	int64	更新时间（毫秒）
account_holder	AccountHolder	账户持有人（主体）信息
metadata	map<string, object>	附加键值对

CURL 请求

curl --location --request GET 'https://openplatform.gateapi.io/merchant/open/institution/v1/accounts/query?request_id=35778162074976257' \
--header 'X-GatePay-Certificate-ClientId: aTEPWRmyiaBapQUb' \
--header 'X-GatePay-Timestamp: 1763359927439' \
--header 'X-GatePay-Nonce: 8936028189' \
--header 'X-GatePay-Signature: 5277b95af7aaa506ed9336ddc1b08fc63d5e4106577f3852453d87c2010230b55cffc15d417c35ca7b1fb9016e9143be4c6e1c5c281d82795b79fe075e313f13' \
--header 'Content-Type: application/json' \

响应:

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "request_id": "35778162074976257",
    "account_id": "2124538349",
    "customer_id": "1234",
    "display_name": "new name",
    "status": "ACTIVE",
    "created": 1763469689743,
    "updated": 1764141615061,
    "account_holder": {
      "entity_country": "AF",
      "entity_type": "BUSINESS",
      "entity_name": null,
      "entity_id_type": "BUSINESS_LICENSE",
      "entity_id_number": "abcd1234",
      "entity_id_expiry": {
        "valid_from": 1763538010509,
        "valid_to": null
      },
      "dob": null,
      "business_registration": null,
      "address": null,
      "merchant_category": "GENERAL_RETAIL",
      "website": null,
      "user_agreement": true
    },
    "metadata": null
  }
}

2.1.4 分页查询子账户

• API描述：分页查询出子账户

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/v1/accounts/list

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
status	string	否	状态 已创建-ACTIVE
request_id	string	否	创建申请单号
customer_id	string	否	平台侧客户 ID
created_gte	int64	否	创建时间毫秒时间戳 ≥
created_lte	int64	否	创建时间毫秒时间戳 ≤
limit	int	否	分页大小，默认20，最大200
cursor	int	否	页码，从1开始

• 响应内容

字段名	类型	说明
accounts	[]AccountInfo	子账户列表
has_more	bool	是否还有下一页

AccountInfo:

字段名	类型	说明
request_id	string	创建申请单号
account_id	string	子账户 ID
customer_id	string	平台侧客户 ID
display_name	string	展示名
status	string	账户状态 初始态-INIT 处理中-PENDING 已创建-ACTIVE 创建失败-FAIL
created	int64	创建时间（毫秒）

CURL 请求

curl --location --request GET 'https://openplatform.gateapi.io/merchant/open/institution/v1/accounts/list?cursor=1&limit=20&request_id=35778162074976257' \
--header 'X-GatePay-Certificate-ClientId: aTEPWRmyiaBapQUb' \
--header 'X-GatePay-Timestamp: 1763359927439' \
--header 'X-GatePay-Nonce: 8936028189' \
--header 'X-GatePay-Signature: 5277b95af7aaa506ed9336ddc1b08fc63d5e4106577f3852453d87c2010230b55cffc15d417c35ca7b1fb9016e9143be4c6e1c5c281d82795b79fe075e313f13' \
--header 'Content-Type: application/json' \

响应:

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "accounts": [
      {
        "request_id": "35778162074976257",
        "account_id": "2124543768",
        "customer_id": "1234",
        "display_name": "my test",
        "status": "ACTIVE",
        "created": 1764139266551
      }
    ],
    "has_more": false
  }
}

2.1.5 回调通知

创建子账户成功通知:

字段名	类型	说明
bizType	string	描述通知类别， INSTITUTION-创建子账户
bizId	string	创建申请单号
bizStatus	string	业务状态 INSTITUTION_ACCOUNT_SUCCESS-创建成功 INSTITUTION_ACCOUNT_FAIL-创建失败
client_id	string	创建子账户的商户client_id
data	content	消息内容，json字符串

content

字段名	类型	说明
request_id	string	创建申请单号
account_id	string	子账户 ID
customer_id	string	平台侧客户 ID
display_name	string	展示名
status	string	账户状态 已创建-ACTIVE 创建失败-FAIL
created	int64	创建时间（毫秒）

创建子账户成功通知，举例:

{
  "bizType": "INSTITUTION",
  "bizId": "35778162074976257",
  "bizStatus": "INSTITUTION_ACCOUNT_SUCCESS",
  "clientId": "ktBVqBBHrEHJmfZH",
  "data": "{\"request_id\":\"35778162074976257\",\"account_id\":\"2124543768\",\"customer_id\":\"1234\",\"display_name\":\"my test\",\"status\":\"ACTIVE\",\"created\":1764139242707}"
}

消息内容:

{
  "request_id": "35778162074976257",
  "account_id": "2124543768",
  "customer_id": "1234",
  "display_name": "my test",
  "status": "ACTIVE",
  "created": 1764139242707
}

2.2 财务

2.2.1 查询账户余额

• API描述：查询账户余额详情

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /payment/open/institution/v1/balance

• 验证方式：签名验证

• 请求体:["币种1", "币种2"]

• 返回体:

  字段名	类型	说明
  balanceList	数组	查询对应币种的余额列表

• 请求实例

curl --location 'http://openplatform.gateapi.io/payment/open/institution/v1/balance' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: {{X_GatePay_Timestamp}}' \
--header 'X-GatePay-Nonce: {{nonce}}' \
--header 'X-GatePay-Signature: {{sign}}' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'Content-Type: application/json' \
--data '["USDT","BTC"]'

{
    "code": "000000",
    "data": {
        "balanceList": [
            {
                "currency": "BTC",
                "available": "0.01"
            },
            {
                "currency": "USDT",
                "available": "12.34411"
            }
        ]
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

2.2.2 获取资金流水账单

• API描述：获取资金流水账单

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /payment/open/institution/v1/pay/bill/orderlist

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
startTime	int64	是	开始时间，单位毫秒
endTime	int64	是	结束时间，单位毫秒
page	int	是	分页编号，从1开始
count	int	是	获取一页条数，最大500
currency	string	否	搜索币种
financialType	string	否	财务类型：参考财务类型定义，包含收款 (receipt_fi)、付款 (payment_fi)、礼品卡 (giftCard_fi)、奖励 (reward_fi)、下发/提现 (distribution_fi)、退款 (refund_fi)、划转 (transfer_fi)、C2C 转账 (c2cTransfer_fi)、闪兑买 (convert_buy_fi)、闪兑卖 (convert_sell_fi)、闪兑退款 (convert_refund_fi)、法币充值 (otcRecharge_add_fi)、法币提现 (otcWithdraw_fi)、理财派息 (interest_fi) 及其他 (others_fi)
orderType	int	否	查询订单类型: 1-商户订单号 2-GatePay订单号 3-资金流水订单号
orderIdNo	string	否	查询单号

• 响应内容

字段名	类型	说明
total	int	总记录数
hasNext	bool	是否有下一页 true: 表示有 false:表示没有
nextPage	int	下一页page编号,当hasNext为true该字段才有效
balance_history_item_list	array	响应的列表数据,数组类型
merchant_id	int	供货商Id

• balance_history_item_list响应字段定义:

字段名	类型	说明
transactId	string	支付流水单号
transactTime	int64	入账时间，毫秒时间戳
orderId	string	GatePay订单号
merchantTradeNo	string	商户订单号
financialType	string	财务类型
payAmount	string	收支金额
currency	string	收支币种
balance	string	账户余额
balanceCurrency	string	账户余额币种
status	string	PAID表示成功
payer	Int64	Gate 支付付款用户UID
buyer	string	对于Web3支付，该值为付款地址；对于非Web3支付，该值为付款人UID
refund_gate_id	string	退款订单ID
payChannel	string	支付方式: Web3 支付 Gate 支付
fullChain	string	支付网络全称
address	string	商家收款地址
hash	string	交易Hash

• 请求示例:

CURL 请求:

curl --location 'https://openplatform.gateapi.io/v1/pay/bill/orderlist?startTime=1746758276000&endTime=1746772913000&count=3&page=3' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1738934053475' \
--header 'x-GatePay-Nonce: 5417061546' \
--header 'x-GatePay-Signature: b8c4705ff4c1357f2a27925dd180c1e1f4a244148f312a2dee5afbcc6f4b150e9ffceee455c5a298f895d43a64ee829eebdfd262539d45c41f7aee4336fd8c8c'
--header 'X-GatePay-On-Behalf-Of: 10002' 

响应:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "merchant_id": 10002,
        "total": 18,
        "hasNext": true,
        "nextPage": 4,
        "balance_history_item_list": [
            {
                "transactId": "355711415868440576",
                "transactTime": 1746769810346,
                "orderId": "355450733498011648",
                "merchantTradeNo": "1746707644001",
                "financialType": "refund_fi",
                "payAmount": "-1",
                "currency": "USDT",
                "Balance": "934183.9783514209",
                "BalanceCurrency": "USDT",
                "status": "PAID",
                "payer": 10002,
                "buyer": "",
                "fullChain": "",
                "hash": "",
                "address": "TMB5f9CgcnYR365knMXKrMM6aGoYpphquj",
                "payChannel": "mini_pay",
                "refund_gate_id": "13411853592035330"
            },
            {
                "transactId": "355711310076907520",
                "transactTime": 1746769785136,
                "orderId": "355450733498011648",
                "merchantTradeNo": "1746707644001",
                "financialType": "refund_fi",
                "payAmount": "+1",
                "currency": "USDT",
                "Balance": "934184.9783514209",
                "BalanceCurrency": "USDT",
                "status": "PAID",
                "payer": 10002,
                "buyer": "",
                "fullChain": "",
                "hash": "",
                "address": "TMB5f9CgcnYR365knMXKrMM6aGoYpphquj",
                "payChannel": "mini_pay",
                "refund_gate_id": "13411849297068033"
            },
            {
                "transactId": "355711310076907520",
                "transactTime": 1746769785131,
                "orderId": "355450733498011648",
                "merchantTradeNo": "1746707644001",
                "financialType": "refund_fi",
                "payAmount": "-1",
                "currency": "USDT",
                "Balance": "934183.9783514209",
                "BalanceCurrency": "USDT",
                "status": "PAID",
                "payer": 10002,
                "buyer": "",
                "fullChain": "",
                "hash": "",
                "address": "TMB5f9CgcnYR365knMXKrMM6aGoYpphquj",
                "payChannel": "mini_pay",
                "refund_gate_id": "13411849297068033"
            }
        ]
    }
}

2.3 下单

2.3.1 收银台订单

• API描述：下收银台订单

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /payment/open/institution/v1/pay/checkout/order

• 验证方式：签名验证

• 请求体:

字段名	类型	是否必须	说明
merchantTradeNo	string	是	商户订单号
currency	string	是	订单币种，大写形式，如USDT、BTC等
orderAmount	string	是	订单金额，最小值0.000001，最高精度为6位
surchargeAmount	string	否	附加费， 指由消费者承担的费用
toleranceAmount	string	否	容差金额：当订单剩余未付金额 ≤ 设置的容差金额时，系统将自动视为支付成功，无需用户额外补款。
fiatCurrency	string	否	法币币种，大写形式，如EUR、GBP、USD、CNY、JPY、AUD、CAD、CHF
fiatAmount	string	否	法币订单金额，最小值0.01，最高精度为2位
payCurrency	string	否	地址支付的付款币种，不传payCurrency就和currency相同
env	Env type	是	交易来源
goods	goods type	是	商品说明
orderExpireTime	int64	否	订单过期绝对时间单位毫秒。不设置时默认为1小时，最大过期时间为1小时
returnUrl	string	否	订单支付成功后返回跳转地址，最长256字符
cancelUrl	string	否	订单支付失败后返回跳转地址，最长256字符
merchantUserId	int64	是	支付者在商户平台注册时的唯一ID
chain	string	是	所选链名字,商户侧可调用/v1/pay/address/chains接口获取，接口请参考地址支付文档
fullCurrType	string	是	包含链名字的币种字段，对应到具体链的具体币种
channelId	string	否	客户名称

Env type

字段名	类型	是否必须	说明
terminalType	string	是	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS

Goods type

字段名	类型	是否必须	说明
goodsName	string	是	商品名称，最长160字符
goodsDetail	string	否	商品描述，最长256字符
goodsType	string	否	商品分类

返回体：

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

data格式:

字段名	类型	说明
prepayId	string	创建成功的预订单id
currency	string	订单加密货币币种
orderAmount	string	订单金额
surchargeAmount	string	附加费，指由消费者承担的费用
toleranceAmount	string	容差金额：当订单剩余未付金额 ≤ 设置的容差金额时，系统将自动视为支付成功，无需用户额外补款。
fiatCurrency	string	订单法币币种
fiatAmount	string	法币订单金额
terminalType	string	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS
expireTime	int64	订单过期时间，UTC时间戳，millisecond。不设置时默认为1小时，最大过期时间为1小时
qrContent	string	订单二维码以链接的格式返回，开发者需要自己使用工具根据内容生成二维码图片。
location	string	下单成功调起收银台跳转地址
payCurrency	string	地址支付付款币种
payAmount	string	地址支付需要支付的金额
chain	chain 结构	地址支付链信息结构
goodsName	string	商品名称
inUsdt	string	对应的USDT的金额

字段名	类型	说明
chain_type	string	链名称
address	string	订单绑定的链收款地址
fullCurrType	string	包含链名字的币种字段，对应到具体链的具体币种

请求示例:

curl --location 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/checkout/order' \
--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-On-Behalf-Of: 2124538349' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--data '{
    "merchantTradeNo": "163",
    "env": {
        "terminalType": "APP"
    },
    "currency": "USDT",
    "orderAmount": "118.75",
    "merchantUserId": 123,
    "goods": {
        "goodsType": "02",
        "goodsName": "Sipariş Ödemesi - 177",
        "goodsDetail": "Sipariş No : 160"
    },
    "returnUrl": "https://lotkeys.com/tr/gate-payment-response",
    "cancelUrl": "https://lotkeys.com/tr/gate-payment-response",
    "chain": "MATIC",
    "fullCurrType": "USDT_MATIC",
    "channelId": "123456"
}'

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "65466648727916544",
        "fiatCurrency": "",
        "fiatAmount": "",
        "currency": "USDT",
        "terminalType": "APP",
        "expireTime": 1677573665219,
        "qrContent": "http://openplatform.gate.io/qr/GA0cskPehKxQpshvm3Goeve8dHpwCl6yCHLSWUYrLqo=",
        "location": "https://www.gate.com/cashier?prepayid=65466648727916544",
        "payCurrency": "USDT",
        "payAmount": "118.75",
        "chain": {
            "chain_type": "BSC",
            "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
            "fullCurrType": "USDT_EOS"
        },
        "channelId": "123456",
        "goodsName": "Sipariş Ödemesi - 177",
        "inUsdt": "118.75"
    }
}

2.3.2 地址订单

• API描述：下地址订单

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /payment/open/institution/v1/pay/address/create

• 验证方式：签名验证

• 请求体:

字段名	类型	是否必须	说明
merchantTradeNo	string	是	商户系统中的交易号
currency	string	否	订单币种
orderAmount	string	否	订单金额
surchargeAmount	string	否	附加费， 指由消费者承担的费用
toleranceAmount	string	否	容差金额：当订单剩余未付金额 ≤ 设置的容差金额时，系统将自动视为支付成功，无需用户额外补款。
fiatCurrency	string	否	法币币种，大写形式，如EUR、GBP、USD、CNY、JPY、AUD、CAD、CHF
fiatAmount	string	否	法币订单金额，最小值0.01，最高精度为2位
payCurrency	string	否	用户选择的支付币种，非闪兑单不需要传
env	EnvRequest	是	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS
goods	GoodsRequest	是	商品
orderExpireTime	int64	是	商户指定订单过期时间戳，毫秒为单位
returnUrl	string	否	支付完成回调地址
cancelUrl	string	否	取消支付回调地址
merchantUserId	int64	是	支付者在商户平台注册时的唯一ID
chain	string	是	所选链名字
fullCurrType	string	是	包含链名字的币种字段，对应到具体链的具体币种
channelId	string	否	客户名称

EnvRequest

字段名	类型	是否必须	说明
terminalType	string	是	创建订单的终端类型

GoodsRequest

字段名	类型	是否必须	说明
goodsName	string	否	商品名称
goodsDetail	string	否	商品详情

返回体:

字段名	类型	说明
prepayId	string	创建的支付单order id
terminalType	string	创建订单的终端类型
expireTime	string	过期毫秒时间戳
chain	Chain	地址支付支付单绑定的链和地址

Chain

字段名	类型	说明
chain_type	string	链名称
address	string	订单绑定的链收款地址
fullCurrType	string	包含链名字的币种字段

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1673323831902' \
--header 'X-GatePay-Nonce: 6225572445' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'X-GatePay-Signature: 8be2d2efcd59354067cfcde2a38ce5921a0ccf39855331971d0855f79fc7e5218782319e0615559a38c9a95b9e9cd6d6de4b3f4e04a8f81458542c369cef5f10' \
--data-raw '{
"merchantTradeNo": "93840202212210025",
"currency": "BTC",
"orderAmount": "2.1",
"env": {
"terminalType": "MINIAPP"
},
"goods": {
"goodsName": "USDT_PAY_BTC_TEST",
"goodsDetail": "yc"
},
"orderExpireTime": 1673410179000,
"returnUrl": "www.test1.com",
"cancelUrl": "www.test2.com",
"merchantUserId": 1336974,
"chain": "BSC",
"fullCurrType": "BTC_BSC",
"channelId":"123456"
}'

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "prepayId": "47656656276819968",
    "terminalType": "MINIAPP",
    "expireTime": 1673410179000,
    "chain": {
      "chain_type": "BSC",
      "fullCurrType": "USDT_BSC",
      "address": "0x1699dB45Dc502A0395038265fCBC4Fa05d6afFBD"
    }
  }
}

2.3.3 web端订单、扫码订单

• API描述：下web端、扫码待支付订单

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /payment/open/institution/v1/pay/transactions/native

• 验证方式：签名验证

• 请求体:

字段名	类型	是否必须	说明
merchantTradeNo	string	是	商户订单号，不大于32字节
currency	string	否	加密货币币种，大写形式，如USDT、BTC等
orderAmount	string	否	加密货币订单金额，最小值0.000001，最高精度为6位，订单金额范围在[0.0001,500000]
fiatCurrency	string	否	法币币种，大写形式，如EUR、GBP、USD、CNY、JPY、AUD、CAD、CHF
fiatAmount	string	否	法币订单金额，最小值0.01，最高精度为2位
actualCurrency	string	否	商户实际要求入账的币种，如果商户要求入账币种与订单币种不一致，可使用此字段指定实际收入币种
env	Env type	是	交易来源APP、WEB、WAP、MINIAPP、OTHERS
goods	goods type	是	商品说明
orderExpireTime	int64	否	订单过期时间，UTC时间戳，millisecond。不设置时默认为1小时，最大过期时间为1小时
returnUrl	string	否	订单支付成功后返回跳转地址，最长256字符
cancelUrl	string	否	订单支付失败后返回跳转地址，最长256字符
channelId	string	否	客户名称

Env type

字段名	类型	是否必须	说明
terminalType	string	是	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS

Goods type

字段名	类型	是否必须	商品名称，最长160字符
goodsName	string	是	商品名称，最长160字符
goodsDetail	string	否	商品描述，最长256字符

• 返回体:

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

date字段:

字段名	类型	是否必须	说明
prepayId	string	是	创建成功的预订单id
terminalType	string	是	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS
expireTime	int64	是	订单过期时间，单位毫秒。不设置时默认为1小时，最大过期时间为1小时
qrContent	string	是	订单二维码以链接的格式返回，开发者需要自己使用工具根据内容生成二维码图片。
location	string	是	创建订单后，Web支付组件跳转地址

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/transactions/native' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: zb6WUrBDZlRAT7qz' \
--header 'X-GatePay-Timestamp: 1674117221032' \
--header 'x-GatePay-Nonce: 7436636664' \
--header 'x-GatePay-Signature: 11e658cf6b09d917caf9d4bb6ec4493431c55f066a694e58a5571a4a1a114ebc2011d346f340e54a5a2e2edaa172e907742fbdc99b94d009dade4b551daabd07' \
--data-raw '{
    "MerchantTradeNo": "118223456797",
    "currency":"USDT",
    "orderAmount":"1.9",
    "env": {
        "terminalType": "APP"
    },
    "goods": {
            "goodsName": "NF2T",
            "goodsDetail": "nef-book"
    },
    "orderExpireTime":1674118228000,
    "returnUrl":"http://47.99.158.63:8205/payment/callback",
    "channelId":"123456"
}'

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "50984376880599040",
        "terminalType": "APP",
        "expireTime": 1674118228000,
        "location": "https://www.gate.io/webpay?prepayid=55583289224171652",
        "qrContent": "http://openplatform.gate.io/qr/amaA9duknMfGKvM5H77Q0STgoTgVPmbPyuPDzlFvJO8="
    }
}

2.3.4 查询订单详情

• API描述：查询订单详情

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /payment/open/institution/v1/pay/order/query

• 验证方式：签名验证

• 请求体:

字段名	类型	是否必须	说明
prepayId	string	否	预付单信息
merchantTradeNo	string	否	商户订单id。预付单id与此id提供一个即可

• 返回体:

属性名	类型	是否必须	说明
status	string	是	SUCCESS 或者 FAIL
code	string	是	出错代码
data	query order return type	否	支付订单信息
errorMessage	string	否	错误信息

data参数：

属性名	类型	是否必须	说明
prepayId	string	是	预付单id
merchantId	int64	是	用于申请商户账号的Gate UID
merchantTradeNo	string	是	商户订单号
transactionId	string	是	交易id
goodsName	string	是	商品名称
currency	string	是	订单币种
orderAmount	string	是	订单金额
surchargeAmount	string	否	附加费，指由消费者承担的费用
toleranceAmount	string	否	容差金额：当订单剩余未付金额 ≤ 设置的容差金额时，系统将自动视为支付成功，无需用户额外补款。
underpaidAmount	string	否	支付完成后，未支付金额
fiatCurrency	string	否	法币订单币种
fiatAmount	string	否	法币订单金额
fiatRate	string	否	法币-加密货币汇率
status	string	是	订单状态
createTime	int64	是	预付单创建时间，单位毫秒
expireTime	int64	是	预付单过期时间，单位毫秒
transactTime	int64	是	支付完成时间，单位毫秒
order_name	string	是	订单名称
pay_currency	string	是	用户实际支付币种
pay_amount	string	是	用户实际支付金额
expectCurrency	string	否	商家创建订单时，指定营收币种，注：仅在商户指定结算币种的订单详情中返回
actualCurrency	string	否	订单支付完成后，Gate后台实际结算到商户账户的币种，注：仅在订单Gate结算给商户后才在订单详情中返回
actualAmount	string	否	订单支付完成后，对应Gate后台实际结算到商户账户的币种的金额，注：仅在订单Gate结算给商户后才在订单详情中返回
rate	string	是	闪兑支付时的汇率
channelId	string	否	客户名称
appName	string	否	应用名称
appLogo	string	否	应用Logo
inUsdt	string	否	对应USDT金额
channel_type	string	否	渠道类型

请求示例

  curl -X POST -H "Content-Type:application/json" \
        -H "X-GatePay-Certificate-ClientId: aa721ba2-5bad-55e5-b3f9-43f9cbe6d814" \
        -H "x-gateio-payment-timestamp: 1647556285603" \
        -H "x-gateio-payment-nonce: OBBHcyeIQn" \
        -H 'X-GatePay-On-Behalf-Of: 2124538349' \
        -H "x-gateio-payment-signature: 1f020e1ee70a7ced14de42f4293592d43f8a74eab5ba4c3771dc6d215278d889fd0ecd398c1026a003b1351752b34c24cd8288afa7ff7552ca06a2aea992a897" \
        -d '{"merchantTradeNo": "56236"}' https://openplatform.gateapi.io/payment/open/institution/v1/pay/order/query

查询非指定营收币种订单详情，响应示例

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "50620368071692288",
        "merchantId": 10002,
        "merchantTradeNo": "4379824792349592345",
        "transactionId": "",
        "goodsName": "NFT",
        "currency": "GT",
        "orderAmount": "0.1",
        "fiatCurrency": "",
        "fiatAmount": "",
        "fiatRate": "",
        "status": "EXPIRED",
        "createTime": 1674030436229,
        "expireTime": 1663054706000,
        "transactTime": 0,
        "order_name": "MiniApp-Payment#4379824792349592345",
        "pay_currency": "",
        "pay_amount": "0",
        "rate": "0",
        "channel_type": "",
        "inUsdt": "",
        "appLogo": "https://gimg2.gateimg.com/image/432c2715a0eaa6217af7a3db1e85ffc8dc866233.webp",
        "appName": "Latiago",
        "channelId":"123456"
    }
}

查询指定营收币种订单详情，未结算，响应示例

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "56335302571069440",
        "merchantId": 10002,
        "merchantTradeNo": "118223456798",
        "transactionId": "",
        "goodsName": "NF2T",
        "currency": "USDT",
        "orderAmount": "1.9",
        "fiatCurrency": "",
        "fiatAmount": "",
        "fiatRate": "",
        "status": "EXPIRED",
        "createTime": 1675392982792,
        "expireTime": 1675396480000,
        "transactTime": 0,
        "order_name": "MiniApp-Payment#118223456798",
        "pay_currency": "",
        "pay_amount": "0",
        "expectCurrency": "BTC",
        "channel_type": "",
        "inUsdt": "",
        "appLogo": "https://gimg2.gateimg.com/image/432c2715a0eaa6217af7a3db1e85ffc8dc866233.webp",
        "appName": "Latiago",
        "rate": "0"
    }
}

查询指定营收币种订单详情，已结算，响应示例

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "56416503889661952",
        "merchantId": 10002,
        "merchantTradeNo": "1182234567119",
        "transactionId": "56416503889661952",
        "goodsName": "NF2T",
        "currency": "GT",
        "orderAmount": "1",
        "fiatCurrency": "",
        "fiatAmount": "",
        "fiatRate": "",
        "status": "PAID",
        "createTime": 1675412342695,
        "expireTime": 1675414420000,
        "transactTime": 1675412385904,
        "order_name": "MiniApp-Payment#1182234567119",
        "pay_currency": "BTC",
        "pay_amount": "1",
        "expectCurrency": "USDT",
        "actualCurrency": "USDT",
        "actualAmount": "1",
        "rate": "1",
        "channel_type": "",
        "inUsdt": "",
        "appLogo": "https://gimg2.gateimg.com/image/432c2715a0eaa6217af7a3db1e85ffc8dc866233.webp",
        "appName": "Latiago",
        "channelId":"123456"
    }
}

2.3.5 取消订单

• API描述：取消订单

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /payment/open/institution/v1/pay/order/close

• 验证方式：签名验证

• 请求体:

字段名	类型	是否必须	说明
merchantTradeNo	string	否	商户订单号，不大于32字节
prepayId	string	否	prepayId merchantTradeNo 只需提供一个

• 返回体:

属性名	类型	是否必须	说明
status	string	是	SUCCESS 或者 FAIL
code	string	是	出错代码
data	close result type	是	关闭结果
errorMessage	string	否	错误信息

close result type

属性名	类型	是否必须	说明
result	string	是	SUCCESS 或者 FAIL

请求示例

curl --location 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/order/close' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: {{X_GatePay_Timestamp}}' \
--header 'X-GatePay-Nonce: {{nonce}}' \
--header 'X-GatePay-Signature: {{sign}}' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Cache-Control: no-cache' \
--header 'Host: openplatform.gateapi.io' \
--header 'Connection: keep-alive' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--data '{"prepayId":"35771760426090520"}'

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

2.3.6 查询支持的网络和币种

• API描述：查询支持的网络和币种

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

字段名	类型	是否必须	说明
X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/v1/pay/fixedaddress/chains

• 验证⽅式：商户签名验证

接口说明:

查询GatePay支持用于静态地址收款的网络和币种

请求参数:

无

响应参数:

字段名	类型	说明
Chains	[]*FixedChainItem	支持的网络、币种列表

FixedChainItem

字段名	类型	说明
chain	string	网络
showChainNameEn	string	网络英文名称
currencies	string	该网络下支持的币种

请求示例

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/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'  \
--header 'X-GatePay-On-Behalf-Of: 2124538349'

响应示例

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

2.3.7 创建静态收款地址

• API描述：创建静态收款地址

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/v1/pay/fixedaddress/save

• 验证⽅式：商户签名验证

接口说明:

按照指定币种和网络，生成静态收款地址

注意: 若channelId + chain已经存在静态收款地址，则会将请求中的currencies和callbackUrl更新到已绑定信息中

请求参数:

字段名	类型	是否必须	说明
channelId	string	是	客户名称，只支持字母、数字、下划线和破折号，长度不超过50字节
chain	string	是	网络名称
currencies	string	是	要在该静态地址上营收的币种，多币种逗号分隔，例如USDT,BTC
callbackUrl	string	是	该渠道到账回调地址，长度不超过128字节

响应参数:

字段名	类型	说明
channelId	string	客户名称
chain	string	网络名称
address	string	收款地址
currencies	[]string	该网络上的收款币种列表
callbackUrl	string	该渠道下的收款消息回调地址
desc	string	描述
ChainShowEn	string	链的英文名

请求示例

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/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' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--data '{
    "channelId": "smart_shop",
    "chain": "ETH",
    "currencies": "DAI,USDT",
    "callbackUrl": "https://www.abc.com/callback"
}'

响应示例

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

2.3.8 查询静态收款地址列表

• API描述：查询静态收款地址列表

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/v1/pay/fixedaddress/list

• 验证⽅式：商户签名验证

接口说明:

请求参数:

字段名	类型	是否必须	说明
page	int	是	从0开始的非负整数，表示页号
count	int	是	正整数，每页显示条数，最大100

响应参数:

字段名	类型	说明
total	int	总数量
list	[]*FixedAddressItem	静态收款地址列表

FixedAddressItem

字段名	类型	说明
channelId	string	客户名称
chain	string	网络
address	string	收款地址
currencies	[]string	该地址上绑定的收款币种
callbackUrl	string	到账回调地址
createTime	int	创建时间
updateTime	int	首次更新时间
desc	string	描述
ChainShowEn	string	链的英文名
is_risk	int	风险地址 0-正常 1-风险

请求示例

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/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' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'

响应示例

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "total": 2,
    "list": [
      {
        "channelId": "smart_shop1",
        "chain": "ETH",
        "address": "0xE2b3fA811f04FD5Ac6559007795D6Fc74365126B",
        "currencies": [
          "USDC"
        ],
        "callbackUrl": "https://www.abc.com/callback",
        "desc": "",
        "ChainShowEn": "ETH /ERC20",
        "createTime": 1727603135221,
        "updateTime": 1727603135221,
        "is_risk": 0
      },
      {
        "channelId": "smart_shop",
        "chain": "ETH",
        "address": "0x3FdC81C3f549343a3E0706A382035B7B461C0840",
        "currencies": [
          "DAI",
          "USDT"
        ],
        "callbackUrl": "https://www.abc.com/callback",
        "desc": "",
        "ChainShowEn": "ETH /ERC20",
        "createTime": 1727603076963,
        "updateTime": 1727603076963,
        "is_risk": 1
      }
    ]
  }
}

2.3.9 查看静态收款地址详情

• API描述：查看静态收款地址详情

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/v1/pay/fixedaddress/detail

• 验证⽅式：商户签名验证

接口说明:

请求参数:

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

响应参数:

字段名	类型	说明
channelId	string	商户绑定静态地址收款时指定的渠道名称
chain	string	网络
address	string	收款地址
currencies	[]string	该地址上绑定的收款币种
callbackUrl	string	到账回调地址
createTime	int	创建时间
updateTime	int	首次更新时间
desc	string	描述
ChainShowEn	string	链的英文名
is_risk	int	风险地址 0-正常 1-风险

请求示例

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/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' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'

响应示例

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "channelId": "smart_shop",
    "chain": "ETH",
    "address": "0x5178ff5B10c17282834028E0A79cb18586D44B7C",
    "currencies": [
      "DAI",
      "USDT"
    ],
    "callbackUrl": "https://www.abc.com/callback",
    "desc": "",
    "ChainShowEn": "ETH /ERC20",
    "createTime": 1727602420837,
    "updateTime": 1727602430742,
    "is_risk": 0
  }
}

2.3.10 删除静态收款地址

• API描述：删除静态收款地址

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：DELETE

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/v1/pay/fixedaddress/delete

• 验证⽅式：商户签名验证

接口说明:

请求参数:

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

响应参数:

字段名	类型	说明
result	string	ok表示成功，其它表示失败

请求示例

curl --location --request DELETE 'https://openplatform.gateapi.io/merchant/open/institution/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' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'

响应示例

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

2.3.11 查询静态收款码账单列表

• API描述：查询静态收款码账单列表

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /payment/open/institution/v1/pay/fixedaddress/order/query

• 验证⽅式：商户签名验证

接口说明:

请求参数:

字段名	类型	是否必须	说明
channelId	string	是	客户名称
chain	string	是	网络
startTime	int	是	订单创建时间开始，单位毫秒
endTime	int	是	订单创建时间结束，单位毫秒
page	int	否	从0开始的非负整数，表示页号
count	int	否	正整数，每页显示条数，最大5000
address	string	否	收款方Web3地址
fromAddress	string	否	付款方Web3地址
txHash	string	否	交易hash

响应参数:

字段名	类型	说明
total	int	总数量
list	[]*PaymentDetails	静态收款账单列表

PaymentDetails

字段名	类型	说明
chain	string	网络
channelId	string	客户名称
currency	string	币种
address	string	收款方Web3地址
amount	string	到账金额
status	string	订单状态
txTime	int	订单创建时间，单位毫秒
fromAddress	string	付款方Web3地址
txHash	string	交易hash
transactionId	string	交易流水号

请求示例

curl --location 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/fixedaddress/order/query?page=0&count=10&chain=ARBEVM&channelId=123456' \
--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' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'

响应示例

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

2.3.12 创建EVM网络静态收款地址

• API描述：针对同一个客户，创建可同时对应多网络的静态收款地址，仅针对EVM网络

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/fixedaddress/evm/save

• 验证⽅式：商户签名验证

接口说明:

注意: 同一个channelId下，一个网络仅允许创建一个静态收款地址，不能重复创建

请求参数:

字段名	类型	是否必须	说明
channelId	string	是	客户名称，只支持字母、数字、下划线和破折号，长度不超过50字节
callbackUrl	string	是	该渠道到账回调地址，长度不超过128字节
chianCurrencyInfos	List<ChianCurrencyInfo>	是	网络和币种信息

ChianCurrencyInfo对象字段说明	类型	是否必须	说明
chain	string	是	网络名称。仅支持EVM网络支持的EVM网络：ETH,MATIC,ARBEVM,BSC
currencies	[]string	否	该网络上的收款币种列表，不传默认该网络下的所有币种

响应参数:

字段名	类型	说明
channelId	string	客户名称
address	string	收款地址
callbackUrl	string	该渠道下的收款消息回调地址
chainInfos	List<ChainInfo>	包含网络以及网络所支持的币种

ChainInfo对象字段说明	类型	说明
chainShowEn	string	网络的英文名
currencies	[]string	该网络上的收款币种列表

请求示例

curl --location 'https://openplatform.gateapi.io/merchant/open/v1/pay/fixedaddress/evm/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",
  "callbackUrl": "https://www.abc.com/callback",
  "chianCurrencyInfos": [
    {
      "chain": "ETH",
      "currencies": [
      "DAI",
      "USDT"
      ]
    }
  ]
}'

响应示例

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "channelId": "susie",
    "address": "0xE74ac03A2d34A9cEce0A6547b1758C7A8fA10230",
    "callbackUrl": "https://www.abc123.com/callbachttps://www.abc123.com/callbackhttps://www.abc123.com/callbackhttps://www.abc123.com/call",
    "chainInfos": [
      {
        "chainShowEn": "BSC/BEP20",
        "currencies": [
          "USDT"
        ]
      }
    ]
  }
}

2.4 下发

2.4.1 创建下发

• API描述：创建下发

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /withdraw/open/institution/v1/pay/create/payouts

• 验证方式：签名验证

• 请求体:

  字段名	类型	是否必须	说明
  batch_id	string	是	由商户侧生成并保证唯一，只能由大小写字符，数字，下划线组成,最大长度32字符
  withdraw_list	数组对象	是	描述各提现子单详情
  channel_id	string	否	客户名称

  withdraw_list 列表字段:

  字段名	类型	是否必须	说明
  merchant_withdraw_id	string	是	商户生成子单唯一ID,只能由大小写字符，数字，下划线组成，最大长度32字符
  amount	string	是	单笔提现金额,精度最大长度为6位，超过8位会截取后保留
  currency	string	是	提现币种
  chain	string	是	链网络
  address	string	是	提现地址
  memo	string	是	转账等备注信息，TON网络转账时必须填写，不需要时填写可能会导致失败，最大长度为128字符。
  fee_type	Int	是	提现手续费的收取方式： *如果选择内扣，则手续费将从提现金额中收取，到账金额为提现金额扣除手续费； *如果选择外收，则手续费将从账户余额中扣除，到账金额即为提现金额。 存量不传默认为内扣的方式 类型枚举： 0-内扣 1-外收

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/v1/pay/create/payouts' \
--header 'X-GatePay-Certificate-SN: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-raw '{
    "batch_id": "M57143269150",
    "withdraw_list": [
        {
            "merchant_withdraw_id": "e1619185671595",
            "currency": "USDT",
            "amount": "0.01",
            "chain": "ETH",
            "address": "THISISTESTADDRESSFORGATEPAY1",
            "memo": "",
            "fee_type": 0
        }
    ]
}'

响应实例:

{
    "code": "000000",
    "data": {
        "batch_id": "M57143269148"
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

响应体内容:

字段名	类型	说明
batch_id	string	由商户侧生成的唯一ID

2.4.2 下发详情

• API描述：下发详情

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /withdraw/open/institution/v1/pay/payouts/detail

• 验证方式：签名验证

• 请求体:

字段名	类型	是否必须	说明
batch_id	string	是	由商户侧在/v1/pay/withdraw生成的唯一ID
detail_status	string	是	接口查询状态 ALL 全部子订单 INIT 新建子订单 PENDING 待处理子订单 PROCESSING 已提交提现请求，待确认子订单 CHECK 审核中子订单 FAIL 失败子订单 DONE 提现成功子订单

• 响应体内容:

总订单字段

字段名	类型	说明
batch_id	string	批次ID
merchant_id	int64	商家ID
client_id	string	创建订单的商户client_id
status	string	总单的状态
create_time	int64	总单创建时间
withdraw_list	array	子单信息
channel_id	string	客户名称

下发总单状态枚举:

字段名	说明
INIT	新建的订单状态
PROCESSING	下发订单，新建处于处理中的订单状态
PARTIAL	部分成功
FAIL	全部失败
SUCCESS	全部成功

子订单(withdraw_list)列表字段

字段名	类型	说明
id	int64	记录ID
batch_id	string	商家批量提现id
merchant_id	int64	商家ID
channel_id	string	客户名称
suborder_id	string	gatepay生成的子单id
withdraw_id	string	提现的交易id，用这个id查询提现单
chain	string	gate_chain链名称
address	string	提现地址
currency	string	币种
amount	decimal.Decimal	发起提现金额
fee	decimal.Decimal	手续费
tx_id	string	交易hash
timestamp	int64	充提侧操作时间
memo	string	转账memo等备注信息
status	string	状态
merchant_withdraw_id	string	商家提现ID
err_msg	string	发起提现失败原因
create_time	int64	创建时间
update_time	int64	更新时间
fee_type	int8	0-金额为扣款金额，1-金额为到账金额
batch_withdraw_id	string	已废弃
desc	string	非column字段，客户渠道备注
reconciliation_status	int8	提现对账状态 0-未对账 1-对账处理中 2-对账匹配失败 3-对账匹配成功
is_placed	int	0 - 未下单， 1- 已下单
finish_time	int64	订单结束时间
sub_amount	decimal.Decimal	总扣减金额（手续费金额+到账金额）
done_amount	decimal.Decimal	到账金额

下发子单状态枚举

字段名	说明
INT	创建态
PENDING	创建态,订单待处理
PROCESSING	订单处理中
CHECK	审核中
FAIL	钱包提现失败
DONE	提现成功

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/v1/pay/payouts/detail' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-raw '{
    "batch_id":"M57143269150"
}'

响应实例:

{
    "code": "000000",
    "data": {
        "batch_id": "M57143269148",
        "merchant_id": 2124538349,
        "client_id": "mZ96D37oKk-HrWJc",
        "status": "PROCESSING",
        "create_time": 1764048644523,
        "withdraw_list": [
            {
                "id": 634708,
                "batch_id": "M57143269148",
                "merchant_id": 2124538349,
                "suborder_id": "35803766522511370",
                "withdraw_id": "",
                "chain": "ETH",
                "address": "THISISTESTADDRESSFORGATEPAY1",
                "currency": "USDT",
                "amount": 0.01000000,
                "fee": "0",
                "tx_id": "",
                "timestamp": 1764048644540,
                "memo": "",
                "create_time": 1764048644540,
                "update_time": 1764048644891,
                "status": "PENDING",
                "err_msg": "",
                "merchant_withdraw_id": "e1619185671593",
                "desc": "",
                "channel_id": null,
                "finish_time": 0,
                "sub_amount": 0.00000000,
                "done_amount": "0"
            }
        ],
        "channel_id": ""
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

batch_id不存在返回空

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "batch_id": "237394559478075358",
        "merchant_id": 0,
        "client_id": "",
        "status": "",
        "create_time": 0,
        "withdraw_list": []
    }
}

2.5 转账

2.5.1 发起划转-机构给用户转款

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 路径Path: /transfer/open/institution/v1/pay/transfer

• 验证方式：签名验证

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 请求体内容:

字段名	类型	是否必须	说明
merchantBatchNo	string	是	由商户侧生成唯一ID
accountId	string	是	接收人账户ID
currency	string	是	转账币种
amount	string	是	转账金额

• 响应体内容:

字段名	类型	说明
merchantBatchNo	string	批次ID和入参merchantBatchNo值一致

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/transfer' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'X-GatePay-ClientId;' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-raw '{
  "merchantBatchNo": "1234565454511231",
  "currency": "USDT",
  "amount": "1",
  "accountId": "1979044675"
}'

响应实例:

{
    "code": "000000",
    "data": {
        "merchantBatchNo": "1234565454511231"
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

2.5.2 划转-机构给用户的划转详情

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 路径Path: /transfer/open/institution/v1/pay/transfer/detail

• 验证方式：签名验证

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 请求体内容:

字段名	类型	是否必须	说明
merchantBatchNo	string	是	由商户侧生成唯一ID

• 响应体内容:

字段名	类型	说明
merchantBatchNo	string	批次ID和入参merchantBatchNo值一致
status	string	ERROR：失败 EXPIRED：过期 PAID：成功 PENDING：待处理 PROCESSING：处理中 CANCEL：取消 CANCELLED：关单
toAccountId	string	收款账户
fromAccountId	string	出款账户
createTime	long	订单时间 毫秒
currency	string	币种

请求示例:

curl --location --request GET 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/transfer/detail?merchantBatchNo=12345654545' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'X-GatePay-MerchantId: 10002' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-binary '@<body data here>'

响应实例:

{
    "code": "000000",
    "data": {
        "merchantBatchNo": "12345654545",
        "status": "PENDING",
        "fromAccountId": "2124267192",
        "toAccountId": "1979044675",
        "currency": "USDT",
        "amount": "1",
        "createTime": 1763455435851
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

2.6 代扣

2.6.1 发起代扣-用户给机构转款

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 路径Path: /transfer/open/institution/v1/pay/charge

• 验证方式：签名验证

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 请求体内容:

字段名	类型	是否必须	说明
merchantBatchNo	string	是	由商户侧生成唯一ID
accountId	string	是	接收人账户ID
currency	string	是	转账币种
amount	string	是	转账金额

• 响应体内容:

字段名	类型	说明
merchantBatchNo	string	批次ID和入参merchantBatchNo值一致

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/charge' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'X-GatePay-ClientId;' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-raw '{
  "merchantBatchNo": "1234565454511231",
  "currency": "USDT",
  "amount": "1",
  "accountId": "1979044675"
}'

响应实例:

{
    "code": "000000",
    "data": {
        "merchantBatchNo": "1234565454511231"
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

2.6.2 代扣-用户给机构的详情

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 路径Path: /transfer/open/institution/v1/pay/charges/detail

• 验证方式：签名验证

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 请求体内容:

字段名	类型	是否必须	说明
merchantBatchNo	string	是	由商户侧生成唯一ID

• 响应体内容:

字段名	类型	说明
merchantBatchNo	string	批次ID和入参merchantBatchNo值一致
status	string	ERROR：失败 EXPIRED：过期 PAID：成功 PENDING：待处理 PROCESSING：处理中 CANCEL：取消 CANCELLED：关单
toAccountId	string	收款账户
fromAccountId	string	出款账户
createTime	long	订单时间 毫秒
currency	string	币种

请求示例:

curl --location --request GET 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/transfer/detail?merchantBatchNo=12345654545' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'X-GatePay-MerchantId: 10002' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-binary '@<body data here>'

响应实例:

{
    "code": "000000",
    "data": {
        "merchantBatchNo": "12345654545",
        "status": "PENDING",
        "fromAccountId": "2124267192",
        "toAccountId": "1979044675",
        "currency": "USDT",
        "amount": "1",
        "createTime": 1763455435851
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

2.7 退款

2.7.1 创建退款接口

• API描述：创建退款接口

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /payment/open/institution/v2/standard/order/refund

• 验证方式：签名验证

• 请求体:

字段名	类型	是否必须	说明
refundRequestId	string	是	商户退款ID,由商户生成唯一ID并保证小于32字节
prepayId	string	是	订单ID,订单必须是完成支付状态才能发起退款
refundAmount	string	是	退款金额
refundReason	string	是	退款原因
refundStyle	int64	否	退款方式 1:原路退 2:指定退
refundPayChannel	int64	否	退款支付方式 1:Gate 2:Web3
refundToGateUid	string	否	退款至用户id,如果是Gate则必填
refundChain	string	否	退款网络 ,如果是Web3则必填
refundBearType	string	否	退款承担类型 1:需商家承担，2:需用户承担
memo	string	否	退款备注
refundAmountTypeFull	string	否	退款金额类型 1:全部退 2:部分退
needNotify	boolean	否	是否需要通知
refundLimit	boolean	否	退款是否限制次数
refundCurrency	string	否	退款币种
refundFundStatementId	int64	否	发起退款的流水id
refundSource	int64	否	退款发起的源头，0：订单 1：流水

• 响应参数:

字段名	类型	说明
refundRequestId	string	商户退款请求Id
prepayId	string	订单Id
refundGateId	string	Gatepay退款单Id
orderAmount	string	订单金额
refundAmount	string	退款金额
errMsg	string	错误信息
orderCurrency	订单币种	订单币种
payCurrency	订单币种	退款币种
payAmount	订单币种	商家支付金额

请求示例：

curl --location --request POST 'https://openplatform.gateapi.io/payment/open/institution/v2/standard/order/refund' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'GatePay-client-Type: IOS' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-raw '{
    "prepayId": "1991810932510167040",
    "refundRequestId": "lux202511x=093726",
    "refundStyle": 2,
    "refundToGateUid":2124538349,
    "refundAmount": "0.018",
    "currency": "USDT",
    "refundPayChannel": 1,
    "refundReason":"test",
    "refundBearType":1
}'

响应示例：

{
  "code": "000000",
  "data": {
    "refundRequestId": "lux202511x=093725",
    "refundGateId": "35803047115358215",
    "prepayId": "1991810932510167040",
    "orderAmount": "1.1",
    "refundAmount": "0.018",
    "errMsg": "",
    "orderCurrency": "USDT",
    "payCurrency": "USDT",
    "payAmount": "0.018"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.7.2 查询退款详情查询接口

• API描述：查询退款详情查询接口

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /payment/open/institution/v2/pay/refund/details

• 验证方式：签名验证

• 请求体:

属性名	类型	是否必须	说明
refundRequestId	string	是	商户生成的退款单id。退款单id必须唯一，不大于32字符

• 响应参数:

属性名	类型	说明
refundRequestId	string	商户退款订单号
gateRefundId	string	退款单id，GatePay生成
refundId	string	商家退款订单号
orderId	string	GatePay支付订单号
merchantTradeNo	string	商户订单号
createTime	int64	退款单创建时间
transactTime	int64	支付时间
transactionId	string	支付流水订单号
txHash	string	交易Hash,Web3退款才有
orderAmount	string	订单金额
orderCurrency	string	订单币种
requestAmount	string	申请退款金额
requestCurrency	string	申请退款币种
amount	string	退款金额
currency	string	退款币种
status	string	退款状态
remark	string	退款订单备注
refund_style	string	退款方式 1:原路退 2:指定退
refund_pay_channel	string	退款支付方式 1:gate 2:web3
refund_address	string	退款地址
refund_chain	string	退款网络
refund_bear_type	string	退款承担类型 1:需商家承担，2:需用户承担
refund_amount_type	string	退款金额类型 1:全部退 2:部分退
refund_account_type	string	退款扣款账户类型，1:支付账户 2:现货账户
refund_gas_amount	string	退款手续费，只有退到web3有
refund_fail_reason	string	退款失败原因
refund_to_gate_uid	string	退款至gate用户uid
channelId	string	客户渠道名称
nickName	string	用户昵称
payerId	string	用户UID
fromAddress	string	付款地址
payChannel	string	支付方式: Web3 支付 Gate 支付
billType	string	账单类型
goodsName	string	商品名称
totalRequestAmount	string	订单维度-申请退款金额
totalRequestCurrency	string	订单维度-申请退款币种
totalReceiveAmount	string	订单维度-实际到账订单金额
totalReceiveCurrency	string	订单维度-实际到账订单币种
refundDetails	[] RefundDetailItem	退款单详情列表

RefundDetailItem 结构:

字段名	类型	说明
transactionId	string	支付流水订单号
transactTime	int64	支付时间
payChannel	string	支付渠道
status	string	支付状态
amount	string	退款金额
currency	string	退款币种
chain	string	网络信息
address	ChainItem	商户收款地址
hash	string	交易hash
remark	string	备注
billType	string	账单类型

退款单Status枚举值：

值	解释
PENDING	订单待支付
PROCESS	订单处理中
CHECK	订单审核中
SUCCESS	退款成功
FAIL	退款失败

请求示例代码

curl --location --request GET 'https://openplatform.gateapi.io/payment/open/institution/v2/pay/refund/details?refundRequestId=lux202511x=093726' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'GatePay-client-Type: IOS' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-raw ''

返回示例

{
  "code": "000000",
  "data": {
    "refundRequestId": "lux202511x=093725",
    "gateRefundId": "35803047115358215",
    "refundId": "lux202511x=093725",
    "orderId": "1991810932510167040",
    "merchantTradeNo": "lux202511x=0937",
    "createTime": 1764047402963,
    "transactTime": 1764047403042,
    "transactionId": "35803047115358215",
    "txHash": "",
    "orderAmount": "1.1",
    "orderCurrency": "USDT",
    "requestAmount": "0.018",
    "requestCurrency": "USDT",
    "amount": "0.018",
    "currency": "USDT",
    "status": "SUCCESS",
    "remark": "test",
    "channelId": "",
    "nickName": null,
    "payerId": 2124538349,
    "fromAddress": "",
    "refundDetails": null,
    "payChannel": "",
    "billType": 2,
    "goodsName": "Goods",
    "totalRequestAmount": "0.126",
    "totalRequestCurrency": "USDT",
    "totalReceiveAmount": "1.1",
    "totalReceiveCurrency": "USDT",
    "refund_style": 2,
    "refund_pay_channel": 1,
    "refund_address": "",
    "refund_chain": "",
    "refund_bear_type": 1,
    "refund_amount_type": 0,
    "refund_account_type": 0,
    "refund_gas_amount": "0",
    "refund_fail_reason": "",
    "refund_to_gate_uid": 2124538349
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.8 闪兑

2.8.1 查询可用闪兑币种

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /transfer/open/institution/v1/pay/convert/currency

• 验证方式：签名验证

• 请求参数 (Query String):

  字段名	类型	是否必须	说明
  side	string	否	交易方向值为( "buy" 或 "sell")

• 响应内容

  字段名	类型	是否必须	说明
  currency	string	是	币种

• CURL 请求

curl --location 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/convert/currency?side=sell' \
--header 'X-GatePay-Certificate-ClientId: SkZlbKOqPoMwnxhl' \
--header 'X-GatePay-Timestamp: 1740018226125' \
--header 'x-GatePay-Nonce: 5241889066' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'x-GatePay-Signature: a428f2afc6103b515d4a774ffe8dda9f10bbe1a9815d4c10598f281e5db014e93c7ae42b6cff0c77166e136e5951261e6bcfc4672582483b814bf604ade50bb4' \
--header 'Content-Type: application/json'

• 响应

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "currency": [
            "USDT",
            "GT",
            "HOOK",
            "ETH",
            "DOT",
            "BTC",
            "DAL",
            "LTC",
            "COS",
            "POL",
            "SOL",
            "DOGE",
            "ALGO",
            "STPT",
            "BCH",
            "SHIB"
        ]
    }
}

2.10.2 查询可用币种对

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /transfer/open/institution/v1/pay/convert/pair

• 验证方式：签名验证

• 请求参数 (Query String):

  字段名	类型	是否必须	说明
  side	string	否	交易方向 交易方向值为( "buy" 或 "sell")
  currency	string	是	币种

• 响应内容

  字段名	类型	是否必须	说明
  pair	string	是	币种对
  sellCurrency	string	是	出售币种
  buyCurrency	string	是	购买币种
  sellCurrencyMax	string	是	出售币种最大数量
  buyCurrencyMax	string	是	购买币种最大数量
  buyCurrencyMin	string	是	购买币种最小数量
  sellCurrencyMin	string	是	出售币种最小数量

• CURL 请求

curl --location 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/convert/pair?currency=GT&side=buy' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1740018611625' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'x-GatePay-Nonce: 3347302609' \
--header 'x-GatePay-Signature: 7209e852c0fca24a9430d097f93331b7d2bac82b2710763a73af67340b67c2d8fef524051d30a3ff42258a93a200b08fdd5849ec2d2fa0f7c7ba9ed52ce38010'

• 响应

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": [
        {
            "pair": "BTC_USDT",
            "sellCurrency": "BTC",
            "sellCurrencyMax": "31",
            "sellCurrencyMin": "0.0002",
            "buyCurrency": "USDT",
            "buyCurrencyMax": "1980000",
            "buyCurrencyMin": "12"
        },
        {
            "pair": "BNB_USDT",
            "sellCurrency": "BNB",
            "sellCurrencyMax": "410",
            "sellCurrencyMin": "0.1",
            "buyCurrency": "USDT",
            "buyCurrencyMax": "100000",
            "buyCurrencyMin": "10"
        } 
    ]
}

2.10.3 预览报价

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /transfer/open/institution/v1/pay/convert/preview

• 验证方式：签名验证

• 请求体内容:

  字段名	类型	是否必须	说明
  buyCurrency	string	是	购买币种
  buyAmount	string	否 与 sellAmount 二选一	购买数量
  sellCurrency	string	是	出售币种
  sellAmount	string	否 与 buyAmount 二选一	出售数量

• 响应内容

  字段名	类型	是否必须	说明
  sellCurrency	string	是	出售币种
  buyCurrency	string	是	购买币种
  sellAmount	string	是	出售数量
  buyAmount	string	是	购买数量
  rate	string	是	价格
  quoteId	string	是	报价ID

• CURL 请求

curl --location 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/convert/preview' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1740019013818' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'x-GatePay-Nonce: 9722139164' \
--header 'x-GatePay-Signature: 8504fe097f7297f8952c76e628ce59dbc93d1df64c95f26c73140ef365d4aa1471826ada0534315461682ec35c131d7e133c51d2ab0822fe7366650a111887ba' \
--data '{
    "buyCurrency":"USDT",
    "buyAmount":"1",
    "sellCurrency":"GT"

}'

• 响应

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "sellCurrency": "GT",
        "buyCurrency": "USDT",
        "buyAmount": "1",
        "sellAmount": "0.04466796",
        "rate": "22.38741462",
        "quoteId": "PAY-16991c65"
    }
}

2.10.4 发起闪兑

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /transfer/open/institution/v1/pay/convert

• 验证方式：签名验证

• 请求体内容:

  字段名	类型	是否必须	说明
  clientReqId	string	是	客户端请求ID(由用户随机生成目的是为了保证幂等)
  quoteId	string	是	报价ID (必须与preview 接口返回的一致 )
  buyAmount	string	是	购买数量 (必须与preview 接口返回的一致 )
  buyCurrency	string	是	购买币种 (必须与preview 接口返回的一致 )
  sellAmount	string	是	出售数量 (必须与preview 接口返回的一致 )
  sellCurrency	string	是	出售币种 (必须与preview 接口返回的一致 )

• 响应内容

  字段名	类型	是否必须	说明
  order_id	string	是	订单ID
  userId	string	是	用户ID
  sellCurrency	string	是	出售币种
  buyCurrency	string	是	购买币种
  sellAmount	string	是	出售数量
  buyAmount	string	是	购买数量
  status	string	是	状态 1 - 创建成功 3 - 成功 6 - 失败
  rate	string	是	价格
  quoteId	string	是	报价ID
  createTime	string	是	创建时间

• CURL 请求

curl --location 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/convert' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1740019013818' \
--header 'x-GatePay-Nonce: 9722139164' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'x-GatePay-Signature: 8504fe097f7297f8952c76e628ce59dbc93d1df64c95f26c73140ef365d4aa1471826ada0534315461682ec35c131d7e133c51d2ab0822fe7366650a111887ba' \
--data '{
    "clientReqId":"181147",
        "sellCurrency": "GT",
        "buyCurrency": "USDT",
        "buyAmount": "1",
        "sellAmount": "0.04464002",
        "price": "22.40142565",
        "quoteId": "PAY-2a5743d8"
}'

• 响应

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "order_id": "327196066546229248",
        "userId": 10002,
        "sellCurrency": "GT",
        "buyCurrency": "USDT",
        "sellAmount": "0.04464002",
        "buyAmount": "1",
        "status": 1,
        "rate": 22.40142365527614,
        "quoteId": "PAY-2a5743d8",
        "createTime": 1739971221273
    }
}

2.10.5 查询闪兑订单

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /transfer/open/institution/v1/pay/convert/order

• 验证方式：签名验证

• 请求参数 (Query String):

  字段名	类型	是否必须	说明
  OrderID	string	是	订单ID

• 响应内容

  字段名	类型	是否必须	说明
  order_id	string	是	订单ID
  userId	string	是	用户ID
  sellCurrency	string	是	出售币种
  buyCurrency	string	是	购买币种
  sellAmount	string	是	出售数量
  buyAmount	string	是	购买数量
  status	string	是	状态 1 - 创建成功 3 - 成功 6 - 失败
  rate	string	是	价格
  quoteId	string	是	报价ID
  createTime	string	是	创建时间

• CURL 请求

curl --location --request GET 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/convert/order?orderId=326850433152987136' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1740021137456' \
--header 'x-GatePay-Nonce: 3735215968' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'x-GatePay-Signature: 77516a1010d9c8d1f0b8e1d72810b62195ca01f8c1000558a7b1b9de4d79c13200d17036d6e4e555bc2bc4a5ca114b44b616dca03b5f9b72687eb34ebee1515d' \
--data '{
    "buyCurrency":"BTC",
    "buyAmount":"1",
    "sellCurrency":"ETH",
    "sellAmount":"0"
}'

• 响应

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "order_id": "326850433152987136",
        "userId": 10002,
        "sellCurrency": "USDT",
        "buyCurrency": "GT",
        "sellAmount": "1",
        "buyAmount": "0.04369692",
        "status": 6,
        "rate": 22.884908135401762,
        "quoteId": "PAY-52f30798",
        "createTime": 1739888815851
    }
}

2.9 otc提现

2.9.1 询价

• API描述：商户创建法币出金订单前,需先询价并获取可执行报价和有效期；在有效期内,报价token将锁定汇率、金额、币种；报价成功后,需要在有效期内使用报价token执行报价并创建订单

• 数据类型：JSON （content-type：application/json）

• 请求方式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /withdraw/open/institution/otc/api/v1/quote

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
cryptoCurrency	string	是	数字货币币种 当前仅支持：USDT
fiatCurrency	string	是	法币币种 当前仅支持：USD
cryptoAmount	string	否	数字货币数量,side为CRYPTO时必传
fiatAmount	string	否	法币数量, side为FIAT时必传
side	string	是	询价方向 CRYPTO：以数字货币为基准询价，此时cryptoAmount必传； FIAT：以法币为基准询价，此时fiatAmount必传
promotionCode	string	否	优惠码
type	string	是	BUY:入金, SELL:出金 本期仅支持SELL

• 响应内容

字段名	类型	说明
cryptoCurrency	string	数字货币币种
fiatCurrency	string	法币币种
cryptoAmount	string	数字货币数量
fiatAmount	string	法币数量
fiatRate	string	法币汇率 法币/数字货币
cryptoRate	string	数字货币汇率 数字货币/法币
validPeriod	integer	询价有效期,单位：秒
quoteToken	string	询价token,下单使用

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/v1/quote' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769588949' \
--header 'x-GatePay-Nonce: 2730095202' \
--header 'x-GatePay-Signature: 7f780aa07e120dda16f0b0139e86a32ebe9833f10b3bf75fafc55dea46658e14a3f18078fa45ecfd9b81b4edf2c0bc91d1d9dc9ca4de5eed3189437f8e31fd69' \
--header 'Content-Type: application/json' \
--data-raw '{
    "cryptoCurrency": "USDT",
    "fiatCurrency": "USD",
    "cryptoAmount": "1000",
    "side": "CRYPTO",
    "type": "SELL"
}'

响应:

{
  "code": "",
  "data": {
    "cryptoCurrency": "USDT",
    "fiatCurrency": "USD",
    "cryptoAmount": "10000",
    "fiatAmount": "9898.72",
    "fiatRate": "0.989872",
    "cryptoRate": "1.01023613",
    "validPeriod": 300,
    "quoteToken": "adhk543"
  },
  "status": "",
  "label": "",
  "errorMessage": ""
}

2.9.2 下单

• API描述：获取报价后,需要在有效期内执行报价并创建法币出金订单

• 数据类型：JSON （content-type：application/json）

• 请求方式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /withdraw/open/institution/otc/api/order/create

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
quoteToken	string	是	询价token
bankAccountId	string	是	银行账户ID
cryptoCurrency	string	是	数字货币币种
fiatCurrency	string	是	法币币种
cryptoAmount	string	是	数字货币数量
fiatAmount	string	是	法币数量
type	string	是	BUY:入金, SELL:出金 本期仅支持SELL
clientOrderId	string	是	商户订单号,下单失败需要变更单号

• 响应内容

字段名	类型	说明
orderId	string	订单ID
status	string	订单状态
createTime	interger	创建时间
createTime	interger	创建时间
clientOrderId	string	商户订单号

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/order/create' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769669668127' \
--header 'x-GatePay-Nonce: 7508857261' \
--header 'x-GatePay-Signature: 9636bd4c3edac24af5ea2b410c38aa0bafc7e73d6333158205a3f3652cfd97e2a94e38a259a057bee565889b1c686a22b03943a196c19d1eaa43ecb5a045cec1' \
--data-raw '{
    "cryptoCurrency": "USDT",
    "fiatCurrency": "USD",
    "cryptoAmount": "10000",
    "fiatAmount": "9800",
    "type": "SELL",
    "quoteToken": "qdfh34543",
    "bankAccountId": "2897434",
    "clientOrderId": "7490324045"
}'

响应:

{
  "code": "000000",
  "data": {
    "orderId": "2016768770965639168",
    "status": "PROCESSING",
    "createTime": 1769670119407,
    "clientOrderId": "7490324045"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.3 查询订单详情

• API描述：执行报价并创建订单后,可以根据返回的订单ID单笔查询订单状态及相关信息

• 数据类型：JSON （content-type：application/json）

• 请求方式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /withdraw/open/institution/otc/api/order/detail

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
orderId	string	否	订单ID,商户订单号为空时必填
clientOrderId	string	否	商户订单号,订单ID为空时必填

• 响应内容

字段名	类型	说明
orderId	string	订单ID
status	string	订单状态 PROCESSING：处理中、FAIL 失败、DONE 成功
cryptoCurrency	string	数字货币币种
fiatCurrency	string	法币币种
type	string	BUY:入金, SELL:出金
cryptoAmount	string	数字货币数量
fiatAmount	string	法币数量
fiatRate	string	法币汇率 法币/数字货币
bankAccountId	string	银行账户ID
createTime	integer	创建时间
updateTime	integer	更新时间
clientOrderId	string	商户订单号
errMsg	string	失败原因

请求示例:

curl --location --request GET 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/order/detail?orderId=35599620284481595' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769670845426' \
--header 'x-GatePay-Nonce: 9099836565' \
--header 'x-GatePay-Signature: 3eef45b012cf9710eb06587775f5fc2807b7445fb0fdd3c830cf453ee07b34824c0b4bf187a1ad783f886c592b04da7b0ab5d8bf47b8741c82bd408db7b811b4' \

响应:

{
  "code": "000000",
  "data": {
    "cryptoCurrency": "USDT",
    "fiatCurrency": "USD",
    "cryptoAmount": "100000",
    "fiatAmount": "99810.08",
    "orderId": "35599620284481595",
    "status": "DONE",
    "createTime": 1761205415973,
    "updateTime": 1761205416189,
    "bankAccountId": "123141284812832183",
    "type": "SELL",
    "fiatRate": "0.9981",
    "clientOrderId": "7490324045"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.4 查询订单列表

• API描述：执行报价并创建订单后,可以根据返回的订单ID批量查询订单状态及相关信息

• 数据类型：JSON （content-type：application/json）

• 请求方式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /withdraw/open/institution/otc/api/order/list

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
status	string	否	订单状态 PROCESSING：处理中、FAIL 失败、DONE 成功
type	string	否	BUY:入金, SELL:出金
cryptoCurrency	string	否	数字货币币种
fiatCurrency	string	否	法币币种
startTime	string	否	创建时间起
endTime	string	否	创建时间止
page	integer	否	页码,默认第1页
pageSize	integer	否	每页数量,默认10条,最大500条
clientOrderId	string	否	商户订单号

• 响应内容

字段名	类型	说明
data	array	订单列表
data[].order_id	string	订单ID
data[].status	string	订单状态
data[].cryptoCurrency	string	数字货币币种
data[].fiatCurrency	string	法币币种
data[].bankAccountId	string	银行账户ID
data[].cryptoAmount	string	数字货币数量
data[].fiatAmount	string	法币数量
data[].fiatRate	string	法币汇率 法币/数字货币
data[].createTime	integer	创建时间
data[].updateTime	integer	更新时间
data[].type	string	BUY:入金 SELL:出金
data[].clientOrderId	string	商户订单号
data[].errMsg	string	失败原因
page	integer	当前页
pageSize	integer	每页数量
total	integer	总条数

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/order/list' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \
--data-raw '{
    "page": 1,
    "pageSize": 10
}'

响应:

{
  "code": "000000",
  "data": {
    "page": 1,
    "pageSize": 10,
    "total": 49,
    "data": [
      {
        "cryptoCurrency": "USDT",
        "fiatCurrency": "USD",
        "cryptoAmount": "10000",
        "fiatAmount": "99810.08",
        "orderId": "2016769960466059264",
        "status": "DONE",
        "createTime": 1769670404763,
        "updateTime": 1769670720469,
        "type": "SELL",
        "bankAccountId": "2897434",
        "fiatRate": "0.9981",
        "clientOrderId": "980932432"
      },
      {
        "cryptoCurrency": "USDT",
        "fiatCurrency": "USD",
        "cryptoAmount": "10000",
        "fiatAmount": "99810.08",
        "orderId": "2016768770965639168",
        "status": "DONE",
        "createTime": 1769670119407,
        "updateTime": 1769670300606,
        "type": "SELL",
        "bankAccountId": "2897434",
        "fiatRate": "0.9981",
        "clientOrderId": "980932433"
      }
    ]
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.5 查询银行账户可选国家列表

• API描述：如需要添加银行账户，可以先查询添加银行账户可选的国家列表信息

• 数据类型：JSON （content-type：application/json）

• 请求方式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /withdraw/open/institution/otc/api/bank/country/list

• 验证方式：签名验证

• 请求体内容:

• 响应内容

字段名	类型	说明
data	array	国家列表
data[].countryId	int	国家id
data[].countryName	string	国家名称
data[].countryCn	string	国家名称中文

请求示例:

curl --location --request GET 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/bank/country/list' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \

响应:

{
  "code": "000000",
  "data": [
    {
      "countryId": 260,
      "countryCn": "阿富汗",
      "countryName": "Afghanistan"
    },
    {
      "countryId": 3,
      "countryCn": "阿尔巴尼亚",
      "countryName": "Albania"
    },
    {
      "countryId": 4,
      "countryCn": "阿尔及利亚",
      "countryName": "Algeria"
    }
  ],
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.6 创建银行账户

• API描述：OTC法币出金时需要新增银行账户；新增银行账户时，需要同时上传银行对账单文件

• 数据类型：JSON （content-type：multipart/form-data）

• 请求方式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /withdraw/open/institution/otc/api/bank/create

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
bankAccountName	string	是	银行账户名称
bankName	string	是	银行名称
countryId	int	是	国家ID
address	string	是	银行地址
iban	string	是	账号/IBAN
swift	string	是	swift
remittanceLineNumber	string	否	路由/清算代码
agentBankName	string	否	代理银行名称
agentBankSwift	string	否	代理银行swift
file	file	是	文件不超过4MB,只允许jpg、jpeg、png;3个月内出具的银行对账单，银行账户名称必须与身份认证的姓名完全一致，若因语种等原因导致差异，请提供相关证明（比如银行证明文件、护照、政府更名回执等）

• 响应内容

字段名	类型	说明
bankAccountId	string	银行账户ID

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/bank/create' \
--header 'X-GatePay-MerchantId;' \
--form 'bankAccountName="bank001"' \
--form 'bankName="bankName01"' \
--form 'countryId="260"' \
--form 'address="123"' \
--form 'iban="123213213"' \
--form 'swift="21321"' \
--form 'remittanceLineNumber="312"' \
--form 'agentBankName="213"' \
--form 'agentBankSwift="454"' \
--form 'file=@"/Downloads/bank.jpg"'

响应:

{
  "code": "000000",
  "data": {
    "bankAccountId": "2897434"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.7 查询银行账户列表

• API描述：支持查询已绑定的银行账户信息，查询后返回商户全量银行账户信息

• 数据类型：JSON （content-type：application/json）

• 请求方式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /withdraw/open/institution/otc/api/bank/list

• 验证方式：签名验证

• 请求体内容: (模糊查询)

字段名	类型	是否必须	说明
bankAccountName	string	否	银行账户名称
iban	string	否	账号/IBAN
swift	string	否	swift
bankName	string	否	银行名称

• 响应内容

字段名	类型	说明
data	array	列表
data[].bankAccountId	string	银行账户ID
data[].bankAccountName	string	银行账户名称
data[].bankName	string	银行名称
data[].countryId	int	国家ID
data[].countryName	string	国家名称
data[].address	string	银行地址
data[].iban	string	账号/IBAN
data[].swift	string	swift
data[].remittanceLineNumber	string	路由/清算代码
data[].agentBankName	string	代理银行名称
data[].agentBankSwift	string	代理银行swift

请求示例:

curl --location --request GET 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/bank/list?bankAccountName=bank001&bankName=bankName01&iban=123213213&swift=21321' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \

响应:

{
  "code": "000000",
  "data": [
    {
      "bankAccountId": 501,
      "bankAccountName": "12312",
      "bankName": "123123",
      "countryId": 260,
      "countryName": "Afghanistan",
      "address": "123123",
      "iban": "12313123",
      "swift": "123132123",
      "remittanceLineNumber": "3123123",
      "agentBankName": "",
      "agentBankSwift": ""
    },
    {
      "bankAccountId": 642,
      "bankAccountName": "testname",
      "bankName": "123123",
      "countryId": 11,
      "countryName": "Australia",
      "address": "123123",
      "iban": "UYTU****GFHG",
      "swift": "13123",
      "remittanceLineNumber": "1231",
      "agentBankName": "",
      "agentBankSwift": ""
    }
  ],
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.8 删除银行账户

• API描述：支持删除指定银行账户信息

• 数据类型：JSON （content-type：application/json）

• 请求方式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /withdraw/open/institution/otc/api/bank/delete

• 验证方式：签名验证

• 请求体内容:

  字段名	类型	是否必须	说明
  bankAccountId	string	是	银行账户ID

• 响应内容

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/bank/delete' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \
--data-raw '{
    "bankAccountId": 796
}'

响应:

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

2.10 客户管理

2.10.1 新增客户

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

• 数据类型：JSON （content-type： application/json）
• 请求方式：POST
• Path: /merchant/open/institution/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	否	自定义字段列表
email	string	否	邮箱

Custom Type

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

请求示例:

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/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' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'
--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.10.2 查询客户

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

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

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

请求示例:

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/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' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'
--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	自定义字段列表
email	string	邮箱

Custom Type

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

2.10.3 修改客户

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

• 数据类型：JSON （content-type： application/json）
• 请求方式：PUT
• Path: /merchant/open/institution/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	否	自定义字段列表
email	string	否	邮箱

Custom Type

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

请求示例:

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/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' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'
--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.10.4 删除客户

删除客户信息。

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

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

请求示例:

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/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' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'
--data '{
    "channelId": "test"
}'

响应：

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

响应字段：

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

2.10.5 商户接入客户管理步骤

Gate Pay接入准备

请参考Gate Pay接入准备文档

新增客户

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

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

常见问题

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

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

Q:为什么客户删除失败

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

2.11 理财

2.11.1 操作理财服务状态

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：POST

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/v1/wealth/action

• 验证方式：签名验证

• 请求体内容:

  字段名	类型	是否必须	说明
  action	string	是	操作类型 关闭-CANCEL 开通-SIGN

• 响应内容

  字段名	类型	是否必须	说明
  account_id	string	是	子账户 ID
  status	string	是	操作类型 关闭-CANCEL 开通-SIGN

• CURL 请求

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/wealth/action' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1740019013818' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'x-GatePay-Nonce: 9722139164' \
--header 'x-GatePay-Signature: 8504fe097f7297f8952c76e628ce59dbc93d1df64c95f26c73140ef365d4aa1471826ada0534315461682ec35c131d7e133c51d2ab0822fe7366650a111887ba' \
--data '{
    "action":"SIGN"
}'

• 响应

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "status": "SIGN",
        "account_id": "2124766106"
    }
}

2.11.2 查询理财服务状态

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 请求header：

  字段名	类型	是否必须	说明
  X-GatePay-Certificate-ClientId	string	是	商户在Gate商户后台注册应用时分配的clientId
  X-GatePay-Timestamp	string	是	请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
  X-GatePay-Nonce	string	是	随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
  X-GatePay-On-Behalf-Of	string	是	被代理的机构账户id
  X-GatePay-Signature	string	是	请求签名。GatePay通过此签名来确定此请求是否合法

• 路径Path: /merchant/open/institution/v1/wealth/query

• 验证方式：签名验证

• 响应内容

  字段名	类型	是否必须	说明
  account_id	string	是	子账户 ID
  status	string	是	理财状态 关闭-CANCEL 开通-SIGN
  enabled	long	是	开启时间（毫秒）
  updated	string	是	更新时间（毫秒）

• CURL 请求

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/wealth/query' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1740018611625' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'x-GatePay-Nonce: 3347302609' \
--header 'x-GatePay-Signature: 7209e852c0fca24a9430d097f93331b7d2bac82b2710763a73af67340b67c2d8fef524051d30a3ff42258a93a200b08fdd5849ec2d2fa0f7c7ba9ed52ce38010'

• 响应

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "status": "SIGN",
        "enabled": 1772516898675,
        "updated": 1772519811822,
        "account_id": "2124766106"
    }
}

3. Error Code

3.1 账户

错误码	描述	解决方案
400001	无效请求参数	请检查请求参数是否合法
400002	无效签名	检查签名算法是否正确
400003	请求时间戳超时	检查请求head里的时间戳字段
550226	该request_id已经创建过子账户	检查request_id字段是否已创建过子账户
550227	未查到查询匹配条件对应的子账户	检查入参查询条件

3.2 下单

错误码	描述	解决方案
550142	header里缺失X-GatePay-On-Behalf-Of	正确传递被代理机构账户id
550200	主账号无代理被代理账户权限	创建被代理账户权限
550201	查询资产账户余额待查资产币种不存在	使用正确的待查资产币种

3.3 otc提现

错误码	描述	解决方案
400001	无效请求参数	检查请求参数是否合法
400002	签名校验失败	检查商户签名是否正确
400003	请求时间戳超时	检查请求head里的时间戳字段
400004	API身份秘钥不存在或无效	检查API身份密钥是否存在或有效
400611	余额不足	检查余额
550175	查询订单不存在	请检查订单是否发起过交易或订单号是否正确
5503001	接口限频	稍后重试
5502961	用户所属国家无法提供服务	检查用户所属国家是否允许
5502971	用户不符合otc交易资格	检查用户otc资格
5502761	下单商户订单号重复	更换商户订单号
550018	风控拒绝	稍后重试
550301	用户未完成Global OTC相关认证	-
550302	用户未完成个人OTC专业认证申请	-
550303	用户未完成企业OTC专业认证申请	-
550304	用户OTC专业认证申请被驳回	-
550305	用户OTC专业认证被冻结	-
550306	用户专业认证审核中	-
550307	用户交易额度不足，需要进行提额申请	-
550308	用户提额申请审核中	-
550309	提额申请拒绝，需要重新进行申请	-
550310	用户未绑定银行账户	请绑定银行账户后重试
550311	当前操作受限，请联系客服处理	-
550312	币种禁止提现	-
550313	询价过期	请重新询价并使用新的token下单
550314	幂等校验失败	-
550315	询价金额限制	请调整询价金额，详情可联系客服确认
550316	创建银行账户失败	-
550317	删除银行账户失败	-
550318	优惠码无效	请更换有效优惠码