跳转到主要内容

​
产品概述

通过机构 API，接入机构可以：
  • 创建和管理客户子账户
  • 代表客户发起交易
  • 管理多币种业务
  • 对账余额和账本
  • 构建集成化支付方案
有关请求头、签名规则及回调验签，请参见 认证与安全。

​
支持能力

能力说明典型 API / 模块
收单 / 收款代表子账户创建订单托管收银台、地址订单、Web/二维码订单、订单查询 / 关闭
换汇 / 兑换代表子账户完成币种兑换币种查询、交易对查询、预览、创建、订单查询
出款 / 提现代表子账户执行对外付款出款创建、出款详情
查询查询子账户余额、账本记录、订单列表余额、账单、订单查询
系统内资金划转使用 charge / transfer 进行内部资金划拨Transfer、Charge

​
Core Concepts

​
Key Definitions

ConceptDefinition
Institution AccountThe institution’s master account in GatePay
Sub-accountAn account created by the institution for its customer (account_id)
Customer IDThe customer’s unique identifier on the institution platform (customer_id)
Display NameHuman-readable display name of the 子账户 (display_name)
Account HolderIdentity information of the 子账户 holder (account_holder)
请求 IDInstitution request unique ID for 幂等性 and 对账 (request_id)

​
Charge vs. Transfer

类型DirectionTypical ScenarioAPI
transferInstitution → 子账户Subsidy, settlement distribution, platform rebatePOST /transfer/open/institution/v1/pay/transfer
chargeSub-account → institutionPlatform commission, service-fee deduction, 资金 sweepPOST /transfer/open/institution/v1/pay/charge
Both operations support batch processing with unique merchantBatchNo identifiers.

​
Delegated 请求s and Proxy Headers

​
X-GatePay-On-Behalf-Of Header

For APIs that require delegated calls (operations on behalf of a 子账户), the request must include the X-GatePay-On-Behalf-Of header with the value being the account ID of the delegated subject. When to use:
  • Creating 订单s on behalf of a 子账户
  • Querying a 子账户’s balances
  • Executing transfers or charges involving a 子账户
  • Managing 出款s for a 子账户
Example: 
X-GatePay-On-Behalf-Of: SUB_ACCOUNT_ID_12345

​
General Integration Requirements

​
Common 请求 Headers

All 机构 API requests must include the following headers. For signing and signature verification details, see 认证与安全.
Header必填说明
X-GatePay-Certificate-ClientIdYesClientId assigned after the institution registers an app
X-GatePay-TimestampYesUTC timestamp in milliseconds; requests with time drift exceeding 10 seconds will be rejected
X-GatePay-NonceYesRandom string; recommended length within 32 characters
X-GatePay-SignatureYesHMAC-SHA256 request signature (see authentication guide)
X-GatePay-On-Behalf-OfConditional必填 for delegated calls; value is the 子账户 ID or institution master ID

​
Idempotency and Retry Strategy

Implement request deduplication based on the appropriate unique identifier for each operation type.
ScenarioIdempotency Key字段 NamePurpose
Create 子账户request_idrequest_idPrevent duplicate account creation
Transfer / Charge商户BatchNomerchantBatchNoPrevent duplicate 资金 movements
出款 batchbatch_idbatch_idPrevent duplicate 出款 batches
出款 sub-订单商户_withdraw_idmerchant_withdraw_idPrevent duplicate 出款 entries
Re资金re资金请求IdrefundRequestIdPrevent duplicate re资金
SwapclientReqIdclientReqIdPrevent duplicate conversions
Store these identifiers in your persistent layer and check before processing each request.

​
Typical Interaction Flows

​
Create Sub-account with 回调

Institution → GatePay: POST /merchant/open/institution/v1/accounts/create
  (Includes request_id, customer_id, display_name, account_holder)
  ↓
GatePay → Institution: Acceptance Response (account_id, status=INIT/PENDING)
  ↓
GatePay → Institution: INSTITUTION Callback (final result: ACTIVE or FAILED)
  ↓
Institution: Persist request_id and account_id for idempotency
Key points:
  • Initial response indicates request acceptance, not final status
  • Final status arrives via 回调 通知
  • Use request_id to ensure 幂等性 across retries

​
Sub-account 收款 with Query Fallback

Institution → GatePay: POST /payment/open/institution/v1/pay/checkout/order
  (Create order on behalf of sub-account with X-GatePay-On-Behalf-Of header)
  ↓
Payer → GatePay: Complete payment
  ↓
GatePay → Institution: ORDER Callback (payment completed)
  ↓
Institution (Fallback): POST /payment/open/institution/v1/pay/order/query
  (Confirm order status if callback is missed or uncertain)

​
Implementation Guide

​
Pre-integration Checklist

Complete these items before beginning integration:
Item说明Deliverable
Register app and obtain ClientId必填 for request authenticationClientId credential
Implement signing algorithm必填 to generate request signaturesHMAC-SHA256 implementation
Timestamp and nonce handlingTimestamp in UTC milliseconds; nonce within 32 characters请求 header generation logic
Define delegated-subject routingPlan which requests use institution master vs. On-Behalf-OfIntegration routing table
Implement 回调 verificationAll 回调s follow signature verification回调 validation logic
Idempotency and 重试 strategyPersist request_id, 商户BatchNo, etc.Deduplication layer
For 回调 details, see 通知 & 回调.

​
Account Management Module

​
Create Sub-account

接口: POST /merchant/open/institution/v1/accounts/create Creates a new 子账户 for a customer under the institution’s master account.

​
请求 参数

字段类型必填说明
request_idstringYesUnique institution request ID for 幂等性
customer_idstringYesCustomer’s unique identifier on the institution platform
display_namestringYesHuman-readable display name for the 子账户
account_holderobjectYesIdentity and compliance information (see below)

​
Account Holder Object

字段类型必填说明
entity_countrystringYesISO 3166-1 alpha-2 country code
entity_typestringYesINDIVIDUAL or BUSINESS
entity_id_typestringConditionalID type (e.g., passport, driver’s license)
entity_id_numberstringConditionalID number
entity_id_expirydateConditionalID expiration date (YYYY-MM-DD)
dobdateConditionalDate of birth (YYYY-MM-DD); required when entity_type=INDIVIDUAL
merchant_categorystringYes商户 category enumeration
user_agreementbooleanYesWhether the user accepted the service agreement
addressobjectYesSubject’s address with street, city, state, zip, country

​
响应 字段

字段类型说明
account_idstringUnique 子账户 ID (used in X-GatePay-On-Behalf-Of for delegation)
statusstringAccount status: INIT, PENDING, ACTIVE, or FAILED
request_idstringEchoed from request

​
Sub-account 状态 Lifecycle

状态Meaning
INITAccount initialized; awaiting compliance review
PENDINGUnder review by GatePay compliance team
ACTIVEAccount approved and ready for use
FAILEDAccount approval rejected; see 回调 for failure reason

​
Update Sub-account

接口: POST /merchant/open/institution/v1/accounts/update Updates 子账户 information. This operation performs an overwrite update.

​
请求 参数

字段类型必填说明
account_idstringYesSub-account ID to update (also in X-GatePay-On-Behalf-Of header)
display_namestringNoUpdated display name
account_holderobjectNoUpdated account holder information

​
请求 Headers

HeaderValue说明
X-GatePay-On-Behalf-Ofaccount_idSub-account ID being updated

​
Query Sub-account

接口: GET /merchant/open/institution/v1/accounts/query Queries a single 子账户 by ID or request ID.

​
Query 参数

参数类型必填说明
request_idstringConditionalInstitution request ID from creation
account_idstringConditionalSub-account ID

​
响应 字段

字段类型说明
account_idstringSub-account ID
customer_idstringCustomer ID
display_namestringDisplay name
statusstringCurrent account status
account_holderobjectAccount holder information
created_attimestampAccount creation timestamp

​
List Sub-accounts

接口: GET /merchant/open/institution/v1/accounts/list Lists 子账户s with pagination support.

​
Query 参数

参数类型必填说明
cursorstringNoPagination cursor (start from 1)
limitintegerNoNumber of results per page (default 20, max 100)
statusstringNoFilter by account status

​
Finance Module

​
Query Balance

接口: POST /payment/open/institution/v1/balance Retrieves current balance for the institution or a delegated 子账户 by currency.

​
请求 Body

Provide an array of currency codes: 
{
  "currencies": ["USDT", "BTC", "USD"]
}

​
响应 字段

字段类型说明
currencystring币种 code
availablestringAvailable balance
holdstringHeld amount (in pending 订单s/出款s)
totalstringTotal balance (available + hold)

​
Query Funds Ledger

接口: GET /payment/open/institution/v1/pay/bill/orderlist Queries 资金 movement records (账本 entries) for 对账 and audit purposes.

​
Query 参数

参数类型必填说明
start_timetimestampNoStart of time range (milliseconds)
end_timetimestampNoEnd of time range (milliseconds)
pageintegerNoPage number (1-indexed)
limitintegerNoRecords per page
currencystringNoFilter by currency
typestringNoFilter by 交易 type

​
响应 字段

字段类型说明
ledger_idstringUnique 账本 identifier
typestringTransaction type (deposit, 出款, transfer, etc.)
currencystring币种 of the 交易
amountstringTransaction amount
balance_afterstringBalance after 交易
business_idstringRelated 订单/batch ID
created_attimestampTransaction timestamp

​
Order Management Module

​
托管收银台 Order

接口: POST /payment/open/institution/v1/pay/checkout/order Creates a hosted checkout 订单 on behalf of a 子账户. Customers are redirected to a GatePay-hosted payment page.

​
请求 Headers

HeaderValue
X-GatePay-On-Behalf-Of子账户_id

​
请求 参数

字段类型必填说明
merchant_order_nostringYes商户-generated unique 订单 number
amountstringYesOrder amount in smallest unit (satoshis, cents, etc.)
currencystringYesSettlement currency
pay_currencystringNo币种 customer pays in (if different from settlement)
descriptionstringNoOrder description
return_urlstringNoURL to redirect after payment completion
notify_urlstringNoWebhook URL for payment 通知s

​
响应 字段

字段类型说明
prepayIdstringUnique payment request ID
locationstringRedirect URL to GatePay checkout page
qrContentstringQR code content for mobile payment
payCurrencystring币种 customer will pay in
payAmountstringAmount customer will pay
chainstringBlockchain chain (if cryptocurrency)
addressstringPayment address for direct transfer
fullCurrTypestringFull currency type identifier

​
Address Order

接口: POST /payment/open/institution/v1/pay/address/create Creates a static address payment 订单.

​
请求 Headers

HeaderValue
X-GatePay-On-Behalf-Of子账户_id

​
请求 参数

字段类型必填说明
merchant_order_nostringYesUnique 订单 number
currencystringYesPayment currency
amountstringYesPayment amount
orderExpireTimetimestampYesOrder expiration time (Unix seconds)
notify_urlstringNoWebhook URL

​
Web & QR Order

接口: POST /payment/open/institution/v1/pay/transactions/native Creates a Web or QR code pending 订单 for native wallet payments.

​
请求 Headers

HeaderValue
X-GatePay-On-Behalf-Of子账户_id

​
Query Order

接口: POST /payment/open/institution/v1/pay/order/query Queries the status and details of an existing 订单.

​
请求 Headers

HeaderValue
X-GatePay-On-Behalf-Of子账户_id

​
请求 参数

字段类型必填说明
orderIdstringConditionalGatePay 订单 ID
merchant_order_nostringConditional商户 订单 number

​
Close Order

接口: POST /payment/open/institution/v1/pay/order/close Closes an open 订单 to prevent further payments.

​
请求 Headers

HeaderValue
X-GatePay-On-Behalf-Of子账户_id

​
Static 收款 Address Management

For direct cryptocurrency payments, manage static collection addresses:
Capability接口Method
Query supported chainsGET /merchant/open/institution/v1/pay/fixedaddress/chainsGET
Create / update addressPOST /merchant/open/institution/v1/pay/fixedaddress/savePOST
List addressesGET /merchant/open/institution/v1/pay/fixedaddress/listGET
Get address detailsGET /merchant/open/institution/v1/pay/fixedaddress/detailGET
Delete addressDELETE /merchant/open/institution/v1/pay/fixedaddress/deleteDELETE
Query collection 账本GET /payment/open/institution/v1/pay/fixedaddress/order/queryGET

​
出款 & Withdrawal Module

Create and manage outbound settlements for 子账户s.

​
Create 出款

接口: POST /withdraw/open/institution/v1/pay/create/payouts Creates a 出款 request on behalf of a 子账户.

​
请求 Headers

HeaderValue
X-GatePay-On-Behalf-Of子账户_id

​
请求 参数

字段类型必填说明
batch_idstringYesBatch identifier for 幂等性
merchant_withdraw_idstringYesUnique 提现 ID
currencystringYes出款 currency
amountstringYes出款 amount
addressstringYesRecipient blockchain address
networkstringYesBlockchain network

​
出款 Detail

接口: POST /withdraw/open/institution/v1/pay/payouts/detail Queries detailed information about a 出款.

​
Transfer & Charge Module

​
Transfer (Institution → Sub-account)

接口: POST /transfer/open/institution/v1/pay/transfer Transfers 资金 from the institution account to a 子账户.

​
请求 参数

字段类型必填说明
merchantBatchNostringYesUnique batch number for 幂等性
currencystringYesTransfer currency
amountstringYesTransfer amount
account_idstringYesRecipient 子账户 ID

​
Query Transfer

接口: GET /transfer/open/institution/v1/pay/transfer/detail

​
Charge (Sub-account → Institution)

接口: POST /transfer/open/institution/v1/pay/charge Deducts 资金 from a 子账户 (e.g., commission or service fees).

​
请求 Headers

HeaderValue
X-GatePay-On-Behalf-Of子账户_id

​
请求 参数

字段类型必填说明
merchantBatchNostringYesUnique batch number for 幂等性
currencystringYesCharge currency
amountstringYesCharge amount

​
Query Charge

接口: GET /transfer/open/institution/v1/pay/charges/detail

​
Re资金 Module

​
Create Re资金

接口: POST /payment/open/institution/v2/standard/order/refund Re资金 a previous payment 订单.

​
请求 Headers

HeaderValue
X-GatePay-On-Behalf-Of子账户_id

​
请求 参数

字段类型必填说明
refundRequestIdstringYesUnique re资金 ID for 幂等性
orderIdstringConditionalGatePay 订单 ID
merchant_order_nostringConditional商户 订单 number
amountstringNoPartial re资金 amount (full if omitted)

​
Query Re资金 Detail

接口: GET /payment/open/institution/v2/pay/refund/details

​
Query 参数

参数类型必填说明
refundRequestIdstringYesRe资金 ID from creation

​
币种 Conversion Module

Convert currencies on behalf of a 子账户. For detailed swap procedures, see 币种 Conversion & Swap.
步骤接口Method
Query available currenciesGET /transfer/open/institution/v1/pay/convert/currency?side=buy/sellGET
Query available pairsGET /transfer/open/institution/v1/pay/convert/pair?currency=...&side=...GET
Get 报价 previewPOST /transfer/open/institution/v1/pay/convert/previewPOST
Create swap 订单POST /transfer/open/institution/v1/pay/convertPOST
Query swap 订单GET /transfer/open/institution/v1/pay/convert/order?orderId=...GET

​
请求 Headers (for swap operations)

HeaderValue
X-GatePay-On-Behalf-Of子账户_id

​
Common 错误码

​
Account Management

错误码说明Resolution
400001Invalid request parametersVerify all required fields and data types
400002Invalid signatureCheck signing algorithm and secret key
400003请求 timestamp expiredEnsure system clock is synchronized; time drift must be < 10 seconds
550226request_id already used to create 子账户Idempotency: return previous result or handle gracefully
550227No matching 子账户 foundVerify account_id or request_id is correct

​
Orders & Delegation

错误码说明Resolution
550142Missing X-GatePay-On-Behalf-Of headerVerify delegated subject header is present and correct
550200Master account has no delegation permissionEnable delegation permission in GatePay settings
550201Asset balance currency not foundUse correct currency code; verify account has balance in that currency
For comprehensive error codes, see 错误码 & 最佳实践s.

​
Integration 最佳实践s

LayerRecommendationDetails
API ClientEncapsulate common headersBuild middleware for timestamp, nonce, signature, on-behalf-of
IdempotencyPersist 幂等性 keysStore request_id, 商户BatchNo, re资金请求Id, clientReqId in database
回调 ProcessingUnified 回调 entryVerify signature, check 幂等性, advance state machine, return SUCCESS
Query FallbackBuild query APIsImplement fallback for 订单s, re资金, transfers, 出款s, 账本
ObservabilityMonitor critical pathsAlert on 回调 failures, signature errors, timestamp expiry, PENDING timeouts

​
回调 Implementation

  • Implement a single 回调 receiver endpoint
  • Verify request signature against X-GatePay-Signature
  • Check 幂等性 using relevant IDs (request_id, account_id, batch_id, etc.)
  • Update database state machine
  • Return HTTP 200 with body {"code": "SUCCESS"} to confirm receipt
For 回调 details, see 通知 & 回调.