Skip to main content

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.

​
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: 
/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
HeaderRequiredDescription
X-GatePay-Certificate-ClientIdYesApplication ClientId
X-GatePay-TimestampYesUTC millisecond timestamp
X-GatePay-NonceYesRandom string
X-GatePay-SignatureYesRequest signature
X-GatePay-On-Behalf-OfConditionalRequired 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-MerchantIdConditionalRequired by the fee-setting APIs to identify the current main-merchant context.
  1. Start with Institution Headers
  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