跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.gate.com/llms.txt

Use this file to discover all available pages before exploring further.

​
概述

当前机构文档包含两部分能力：
  • 机构专属 API：子账户、费用设置、代扣、划转、创建子账户结果回调
  • 机构代理商户 API：在标准商户 API 路径中统一加入 institution 前缀，用于机构代表子账户调用完整的商户能力
你可以把机构能力理解为：机构既保留自己的账户与内部资金能力，也提供一套面向子账户代理调用的完整商户 API 体系。

​
机构专属 API

​
子账户

  • POST /merchant/open/institution/v1/accounts/create
  • POST /merchant/open/institution/v1/accounts/update
  • GET /merchant/open/institution/v1/accounts/query
  • GET /merchant/open/institution/v1/accounts/list

​
费用设置

  • POST /rate/commission_rule
  • POST /rate/commission_rule/upgrade
  • GET /rate/commission_rule
  • POST /rate/commission_rule/list
这组接口用于主商户为其子账户配置加价（下文统称为 Markup）规则。若子账户未单独配置 Markup，则默认按主商户底价规则计价，不再叠加子账户级 Markup。

​
资金划转

  • POST /transfer/open/institution/v1/pay/transfer
  • GET /transfer/open/institution/v1/pay/transfer/detail
  • POST /transfer/open/institution/v1/pay/charge
  • GET /transfer/open/institution/v1/pay/charges/detail
在当前版本中，transfer 与 charge 已调整为同步接口：
  • 发起请求后，接口会直接返回最终执行结果
  • 商户不需要再以“提交后轮询详情接口”的方式等待异步处理结果
  • detail 接口保留，用于按 merchantBatchNo 查询历史记录、补查结果或对账核对

​
回调

  • POST /webhook/institution/v1/accounts/callback

​
机构代理商户 API

机构代理商户 API 覆盖以下标准商户能力：
  • 支付
  • 余额
  • OTC
  • 闪兑
  • 出金
  • 礼品卡
  • 订阅
机构代理路径统一在标准商户路径前增加 /payment/open/institution。例如： 
/v1/pay/checkout/order
/payment/open/institution/v1/pay/checkout/order

​
请求头规则

​
不需要 X-GatePay-On-Behalf-Of 的接口

  • POST /merchant/open/institution/v1/accounts/create
  • GET /merchant/open/institution/v1/accounts/query
  • GET /merchant/open/institution/v1/accounts/list
  • GET /rate/commission_rule
  • POST /rate/commission_rule
  • POST /rate/commission_rule/upgrade
  • POST /rate/commission_rule/list

​
需要 X-GatePay-On-Behalf-Of 的接口

  • 代扣与划转接口
  • 所有机构代理商户 API
请求头必填说明
X-GatePay-Certificate-ClientId是应用 ClientId
X-GatePay-Timestamp是UTC 毫秒时间戳
X-GatePay-Nonce是随机字符串
X-GatePay-Signature是请求签名
X-GatePay-On-Behalf-Of有条件机构资金类接口与机构代理商户 API 需要携带；机构代理商户 API 通常填写目标子账户 ID，代扣与划转接口可填写本次请求的发起方账户 ID（机构账户或子账户）；子账户接口和费用设置接口不使用该请求头
X-GatePay-MerchantId有条件费用设置接口必填，用于标识当前主商户上下文

​
推荐阅读顺序

  1. 先阅读 机构请求头
  2. 先跑通子账户创建与查询
  3. 再验证费用设置接口，按“创建 > 更新 > 查询详情 > 查询列表”的顺序确认 Markup 行为符合预期
  4. 再验证 transfer / charge
  5. 最后再接机构代理商户 API

​
相关参考文档