> ## 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：子账户、费用设置、代扣、划转、创建子账户结果回调
* 机构代理商户 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`。例如：

```text theme={null}
/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. 先阅读 [机构请求头](/api-reference/version/100/cn/common/institutionalCommonHeaders)
2. 先跑通子账户创建与查询
3. 再验证费用设置接口，按“创建 > 更新 > 查询详情 > 查询列表”的顺序确认 Markup 行为符合预期
4. 再验证 `transfer` / `charge`
5. 最后再接机构代理商户 API

## 相关参考文档

* [机构请求头](/api-reference/version/100/cn/common/institutionalCommonHeaders)
* [创建子账户](/api-reference/version/100/cn/endpoint/institutional/create)
* [更新子账户](/api-reference/version/100/cn/endpoint/institutional/update)
* [查询子账户详情](/api-reference/version/100/cn/endpoint/institutional/query)
* [分页查询子账户](/api-reference/version/100/cn/endpoint/institutional/list)
* [查询费用配置规则详情](/api-reference/version/100/cn/endpoint/institutional/fee-settings/query)
* [创建费用规则](/api-reference/version/100/cn/endpoint/institutional/fee-settings/create)
* [更新费用规则](/api-reference/version/100/cn/endpoint/institutional/fee-settings/upgrade)
* [查询费用规则列表](/api-reference/version/100/cn/endpoint/institutional/fee-settings/list)
* [发起划转](/api-reference/version/100/cn/endpoint/institutional/transfer)
* [划转详情](/api-reference/version/100/cn/endpoint/institutional/transferDetail)
* [发起代扣](/api-reference/version/100/cn/endpoint/institutional/charge)
* [代扣详情](/api-reference/version/100/cn/endpoint/institutional/chargeDetail)