Skip to main content

​
概述

当前机构文档包含两部分能力：
  • 机构专属 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 /pay-cashier/open/v1/certification/url
  • GET /pay-cashier/open/v1/certification/verify/query

​
费用设置

  • 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
  • POST /webhook/institution/v1/verify/result

​
机构代理商户 API

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

​
请求头规则

​
不需要 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

​
推荐阅读顺序

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

​
相关参考文档