Skip to main content

​
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
  • POST /pay-cashier/open/v1/certification/url
  • GET /pay-cashier/open/v1/certification/verify/query

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

​
Institution Merchant APIs

The institution merchant API set covers:
  • Payment
  • Balance
  • OTC
  • Convert
  • Payout
  • Gift Card
  • Subscription
Institution-prefixed path convention:

​
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
  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