> ## 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.

# Institution

> Explains dedicated institution APIs, institution merchant APIs, header rules, and the recommended integration path.

## Overview

The institution documentation includes two capability layers:

* Dedicated institution APIs: accounts, fee settings, charge, transfer, and the account-creation callback
* Institution Merchant APIs: the full merchant API surface exposed under institution-prefixed paths

## Dedicated Institution APIs

### Accounts

* `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`

### Fee Settings

* `POST /rate/commission_rule`
* `POST /rate/commission_rule/upgrade`
* `GET /rate/commission_rule`
* `POST /rate/commission_rule/list`

These APIs let the institution main merchant configure markup rules for sub-accounts. If a sub-account does not have its own markup rule, pricing falls back to the main merchant base-rate rule without adding any sub-account-level markup.

### Transfer and Charge

* `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`

In the current version, `transfer` and `charge` are **synchronous APIs**:

* Each submit request returns the final execution result directly
* Merchants do not need to rely on a submit-then-poll pattern to wait for asynchronous completion
* The `detail` endpoints are retained for historical lookup, result backfill, and reconciliation checks by `merchantBatchNo`

### Callback

* `POST /webhook/institution/v1/accounts/callback`

## Institution Merchant APIs

The institution merchant API set covers:

* Payment
* Balance
* OTC
* Convert
* Payout
* Gift Card
* Subscription

Institution-prefixed path convention:

```text theme={null}
/v1/pay/checkout/order
/payment/open/institution/v1/pay/checkout/order
```

## Header Rules

### Endpoints that do not use `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`

### Endpoints that require `X-GatePay-On-Behalf-Of`

* Charge and transfer APIs
* All institution merchant APIs

| Header                           | Required    | Description                                                                                                                                                                                                                                                                                                                                          |
| -------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-GatePay-Certificate-ClientId` | Yes         | Application ClientId                                                                                                                                                                                                                                                                                                                                 |
| `X-GatePay-Timestamp`            | Yes         | UTC millisecond timestamp                                                                                                                                                                                                                                                                                                                            |
| `X-GatePay-Nonce`                | Yes         | Random string                                                                                                                                                                                                                                                                                                                                        |
| `X-GatePay-Signature`            | Yes         | Request signature                                                                                                                                                                                                                                                                                                                                    |
| `X-GatePay-On-Behalf-Of`         | Conditional | Required for institution fund-movement APIs and institution merchant APIs. Institution merchant APIs typically use the target sub-account ID; charge and transfer APIs can use the initiating account ID for the current request (either an institution account ID or a sub-account ID). It is not used by the account APIs or the fee-setting APIs. |
| `X-GatePay-MerchantId`           | Conditional | Required by the fee-setting APIs to identify the current main-merchant context.                                                                                                                                                                                                                                                                      |

## Recommended Reading Order

1. Start with [Institution Headers](/api-reference/version/100/en/common/institutionalCommonHeaders)
2. Validate account creation and query first
3. Validate fee settings in the order of create > update > detail query > list query
4. Validate `transfer` and `charge`
5. Extend to institution merchant APIs

## Related References

* [Institution Headers](/api-reference/version/100/en/common/institutionalCommonHeaders)
* [Create Sub-account](/api-reference/version/100/en/endpoint/institutional/create)
* [Update Sub-account](/api-reference/version/100/en/endpoint/institutional/update)
* [Query Sub-account](/api-reference/version/100/en/endpoint/institutional/query)
* [List Sub-accounts](/api-reference/version/100/en/endpoint/institutional/list)
* [Get Fee Rule Configuration Detail](/api-reference/version/100/en/endpoint/institutional/fee-settings/query)
* [Create Fee Rule](/api-reference/version/100/en/endpoint/institutional/fee-settings/create)
* [Update Fee Rule](/api-reference/version/100/en/endpoint/institutional/fee-settings/upgrade)
* [List Fee Rules](/api-reference/version/100/en/endpoint/institutional/fee-settings/list)
* [Initiate Transfer](/api-reference/version/100/en/endpoint/institutional/transfer)
* [Transfer Detail](/api-reference/version/100/en/endpoint/institutional/transferDetail)
* [Initiate Charge](/api-reference/version/100/en/endpoint/institutional/charge)
* [Charge Detail](/api-reference/version/100/en/endpoint/institutional/chargeDetail)