Skip to main content

​
Product Overview

Through the Institution API, institutions can:
  • Create and manage customer sub-accounts
  • Execute transactions on behalf of customers
  • Manage multi-currency operations
  • Reconcile balances and ledgers
  • Build integrated payment solutions
For request headers, signature rules, and callback verification, refer to Authentication & Security.

​
Supported Capabilities

CapabilityDescriptionTypical API / Module
Acquiring / CollectionCreate orders on behalf of a sub-accountHosted checkout, address order, Web/QR order, order query/close
Swap / ConversionConvert currencies on behalf of a sub-accountCurrency query, pair query, preview, create, order query
Payout / WithdrawalMake outbound settlements on behalf of a sub-accountPayout create, payout detail
QueriesQuery sub-account balances, ledger records, order listsBalance, bill, order query
Intra-system fund movementUse charge/transfer for internal fund movementTransfer, 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 sub-account (display_name)
Account HolderIdentity information of the sub-account holder (account_holder)
Request IDInstitution request unique ID for idempotency and reconciliation (request_id)

​
Charge vs. Transfer

TypeDirectionTypical ScenarioAPI
transferInstitution → sub-accountSubsidy, settlement distribution, platform rebatePOST /transfer/open/institution/v1/pay/transfer
chargeSub-account → institutionPlatform commission, service-fee deduction, funds sweepPOST /transfer/open/institution/v1/pay/charge
Both operations support batch processing with unique merchantBatchNo identifiers.

​
Delegated Requests and Proxy Headers

​
X-GatePay-On-Behalf-Of Header

For APIs that require delegated calls (operations on behalf of a sub-account), 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 orders on behalf of a sub-account
  • Querying a sub-account’s balances
  • Executing transfers or charges involving a sub-account
  • Managing payouts for a sub-account
Example: 
X-GatePay-On-Behalf-Of: SUB_ACCOUNT_ID_12345

​
General Integration Requirements

​
Common Request Headers

All Institution API requests must include the following headers. For signing and signature verification details, see Authentication & Security.
HeaderRequiredDescription
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-OfConditionalRequired for delegated calls; value is the sub-account ID or institution master ID

​
Idempotency and Retry Strategy

Implement request deduplication based on the appropriate unique identifier for each operation type.
ScenarioIdempotency KeyField NamePurpose
Create sub-accountrequest_idrequest_idPrevent duplicate account creation
Transfer / ChargemerchantBatchNomerchantBatchNoPrevent duplicate fund movements
Payout batchbatch_idbatch_idPrevent duplicate payout batches
Payout sub-ordermerchant_withdraw_idmerchant_withdraw_idPrevent duplicate payout entries
RefundrefundRequestIdrefundRequestIdPrevent duplicate refunds
SwapclientReqIdclientReqIdPrevent duplicate conversions
Store these identifiers in your persistent layer and check before processing each request.

​
Typical Interaction Flows

​
Create Sub-account with Callback

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 callback notification
  • Use request_id to ensure idempotency across retries

​
Sub-account Collection 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:
ItemDescriptionDeliverable
Register app and obtain ClientIdRequired for request authenticationClientId credential
Implement signing algorithmRequired to generate request signaturesHMAC-SHA256 implementation
Timestamp and nonce handlingTimestamp in UTC milliseconds; nonce within 32 charactersRequest header generation logic
Define delegated-subject routingPlan which requests use institution master vs. On-Behalf-OfIntegration routing table
Implement callback verificationAll callbacks follow signature verificationCallback validation logic
Idempotency and retry strategyPersist request_id, merchantBatchNo, etc.Deduplication layer
For callback details, see Notification & Callbacks.

​
Account Management Module

​
Create Sub-account

Endpoint: POST /merchant/open/institution/v1/accounts/create Creates a new sub-account for a customer under the institution’s master account.

​
Request Parameters

FieldTypeRequiredDescription
request_idstringYesUnique institution request ID for idempotency
customer_idstringYesCustomer’s unique identifier on the institution platform
display_namestringYesHuman-readable display name for the sub-account
account_holderobjectYesIdentity and compliance information (see below)

​
Account Holder Object

FieldTypeRequiredDescription
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_categorystringYesMerchant category enumeration
user_agreementbooleanYesWhether the user accepted the service agreement
addressobjectYesSubject’s address with street, city, state, zip, country

​
Response Fields

FieldTypeDescription
account_idstringUnique sub-account ID (used in X-GatePay-On-Behalf-Of for delegation)
statusstringAccount status: INIT, PENDING, ACTIVE, or FAILED
request_idstringEchoed from request

​
Sub-account Status Lifecycle

StatusMeaning
INITAccount initialized; awaiting compliance review
PENDINGUnder review by GatePay compliance team
ACTIVEAccount approved and ready for use
FAILEDAccount approval rejected; see callback for failure reason

​
Update Sub-account

Endpoint: POST /merchant/open/institution/v1/accounts/update Updates sub-account information. This operation performs an overwrite update.

​
Request Parameters

FieldTypeRequiredDescription
account_idstringYesSub-account ID to update (also in X-GatePay-On-Behalf-Of header)
display_namestringNoUpdated display name
account_holderobjectNoUpdated account holder information

​
Request Headers

HeaderValueDescription
X-GatePay-On-Behalf-Ofaccount_idSub-account ID being updated

​
Query Sub-account

Endpoint: GET /merchant/open/institution/v1/accounts/query Queries a single sub-account by ID or request ID.

​
Query Parameters

ParameterTypeRequiredDescription
request_idstringConditionalInstitution request ID from creation
account_idstringConditionalSub-account ID

​
Response Fields

FieldTypeDescription
account_idstringSub-account ID
customer_idstringCustomer ID
display_namestringDisplay name
statusstringCurrent account status
account_holderobjectAccount holder information
created_attimestampAccount creation timestamp

​
List Sub-accounts

Endpoint: GET /merchant/open/institution/v1/accounts/list Lists sub-accounts with pagination support.

​
Query Parameters

ParameterTypeRequiredDescription
cursorstringNoPagination cursor (start from 1)
limitintegerNoNumber of results per page (default 20, max 100)
statusstringNoFilter by account status

​
Finance Module

​
Query Balance

Endpoint: POST /payment/open/institution/v1/balance Retrieves current balance for the institution or a delegated sub-account by currency.

​
Request Body

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

​
Response Fields

FieldTypeDescription
currencystringCurrency code
availablestringAvailable balance
holdstringHeld amount (in pending orders/payouts)
totalstringTotal balance (available + hold)

​
Query Funds Ledger

Endpoint: GET /payment/open/institution/v1/pay/bill/orderlist Queries fund movement records (ledger entries) for reconciliation and audit purposes.

​
Query Parameters

ParameterTypeRequiredDescription
start_timetimestampNoStart of time range (milliseconds)
end_timetimestampNoEnd of time range (milliseconds)
pageintegerNoPage number (1-indexed)
limitintegerNoRecords per page
currencystringNoFilter by currency
typestringNoFilter by transaction type

​
Response Fields

FieldTypeDescription
ledger_idstringUnique ledger identifier
typestringTransaction type (deposit, payout, transfer, etc.)
currencystringCurrency of the transaction
amountstringTransaction amount
balance_afterstringBalance after transaction
business_idstringRelated order/batch ID
created_attimestampTransaction timestamp

​
Order Management Module

​
Hosted Checkout Order

Endpoint: POST /payment/open/institution/v1/pay/checkout/order Creates a hosted checkout order on behalf of a sub-account. Customers are redirected to a GatePay-hosted payment page.

​
Request Headers

HeaderValue
X-GatePay-On-Behalf-Ofsub-account_id

​
Request Parameters

FieldTypeRequiredDescription
merchant_order_nostringYesMerchant-generated unique order number
amountstringYesOrder amount in smallest unit (satoshis, cents, etc.)
currencystringYesSettlement currency
pay_currencystringNoCurrency customer pays in (if different from settlement)
descriptionstringNoOrder description
return_urlstringNoURL to redirect after payment completion
notify_urlstringNoWebhook URL for payment notifications

​
Response Fields

FieldTypeDescription
prepayIdstringUnique payment request ID
locationstringRedirect URL to GatePay checkout page
qrContentstringQR code content for mobile payment
payCurrencystringCurrency customer will pay in
payAmountstringAmount customer will pay
chainstringBlockchain chain (if cryptocurrency)
addressstringPayment address for direct transfer
fullCurrTypestringFull currency type identifier

​
Address Order

Endpoint: POST /payment/open/institution/v1/pay/address/create Creates a static address payment order.

​
Request Headers

HeaderValue
X-GatePay-On-Behalf-Ofsub-account_id

​
Request Parameters

FieldTypeRequiredDescription
merchant_order_nostringYesUnique order number
currencystringYesPayment currency
amountstringYesPayment amount
orderExpireTimetimestampYesOrder expiration time (Unix seconds)
notify_urlstringNoWebhook URL

​
Web & QR Order

Endpoint: POST /payment/open/institution/v1/pay/transactions/native Creates a Web or QR code pending order for native wallet payments.

​
Request Headers

HeaderValue
X-GatePay-On-Behalf-Ofsub-account_id

​
Query Order

Endpoint: POST /payment/open/institution/v1/pay/order/query Queries the status and details of an existing order.

​
Request Headers

HeaderValue
X-GatePay-On-Behalf-Ofsub-account_id

​
Request Parameters

FieldTypeRequiredDescription
orderIdstringConditionalGatePay order ID
merchant_order_nostringConditionalMerchant order number

​
Close Order

Endpoint: POST /payment/open/institution/v1/pay/order/close Closes an open order to prevent further payments.

​
Request Headers

HeaderValue
X-GatePay-On-Behalf-Ofsub-account_id

​
Static Collection Address Management

For direct cryptocurrency payments, manage static collection addresses:
CapabilityEndpointMethod
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 ledgerGET /payment/open/institution/v1/pay/fixedaddress/order/queryGET

​
Payout & Withdrawal Module

Create and manage outbound settlements for sub-accounts.

​
Create Payout

Endpoint: POST /withdraw/open/institution/v1/pay/create/payouts Creates a payout request on behalf of a sub-account.

​
Request Headers

HeaderValue
X-GatePay-On-Behalf-Ofsub-account_id

​
Request Parameters

FieldTypeRequiredDescription
batch_idstringYesBatch identifier for idempotency
merchant_withdraw_idstringYesUnique withdrawal ID
currencystringYesPayout currency
amountstringYesPayout amount
addressstringYesRecipient blockchain address
networkstringYesBlockchain network

​
Payout Detail

Endpoint: POST /withdraw/open/institution/v1/pay/payouts/detail Queries detailed information about a payout.

​
Transfer & Charge Module

​
Transfer (Institution → Sub-account)

Endpoint: POST /transfer/open/institution/v1/pay/transfer Transfers funds from the institution account to a sub-account.

​
Request Parameters

FieldTypeRequiredDescription
merchantBatchNostringYesUnique batch number for idempotency
currencystringYesTransfer currency
amountstringYesTransfer amount
account_idstringYesRecipient sub-account ID

​
Query Transfer

Endpoint: GET /transfer/open/institution/v1/pay/transfer/detail

​
Charge (Sub-account → Institution)

Endpoint: POST /transfer/open/institution/v1/pay/charge Deducts funds from a sub-account (e.g., commission or service fees).

​
Request Headers

HeaderValue
X-GatePay-On-Behalf-Ofsub-account_id

​
Request Parameters

FieldTypeRequiredDescription
merchantBatchNostringYesUnique batch number for idempotency
currencystringYesCharge currency
amountstringYesCharge amount

​
Query Charge

Endpoint: GET /transfer/open/institution/v1/pay/charges/detail

​
Refund Module

​
Create Refund

Endpoint: POST /payment/open/institution/v2/standard/order/refund Refunds a previous payment order.

​
Request Headers

HeaderValue
X-GatePay-On-Behalf-Ofsub-account_id

​
Request Parameters

FieldTypeRequiredDescription
refundRequestIdstringYesUnique refund ID for idempotency
orderIdstringConditionalGatePay order ID
merchant_order_nostringConditionalMerchant order number
amountstringNoPartial refund amount (full if omitted)

​
Query Refund Detail

Endpoint: GET /payment/open/institution/v2/pay/refund/details

​
Query Parameters

ParameterTypeRequiredDescription
refundRequestIdstringYesRefund ID from creation

​
Currency Conversion Module

Convert currencies on behalf of a sub-account. For detailed swap procedures, see Currency Conversion & Swap.
StepEndpointMethod
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 quote previewPOST /transfer/open/institution/v1/pay/convert/previewPOST
Create swap orderPOST /transfer/open/institution/v1/pay/convertPOST
Query swap orderGET /transfer/open/institution/v1/pay/convert/order?orderId=...GET

​
Request Headers (for swap operations)

HeaderValue
X-GatePay-On-Behalf-Ofsub-account_id

​
Common Error Codes

​
Account Management

Error CodeDescriptionResolution
400001Invalid request parametersVerify all required fields and data types
400002Invalid signatureCheck signing algorithm and secret key
400003Request timestamp expiredEnsure system clock is synchronized; time drift must be < 10 seconds
550226request_id already used to create sub-accountIdempotency: return previous result or handle gracefully
550227No matching sub-account foundVerify account_id or request_id is correct

​
Orders & Delegation

Error CodeDescriptionResolution
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 Error Codes & Best Practices.

​
Integration Best Practices

LayerRecommendationDetails
API ClientEncapsulate common headersBuild middleware for timestamp, nonce, signature, on-behalf-of
IdempotencyPersist idempotency keysStore request_id, merchantBatchNo, refundRequestId, clientReqId in database
Callback ProcessingUnified callback entryVerify signature, check idempotency, advance state machine, return SUCCESS
Query FallbackBuild query APIsImplement fallback for orders, refunds, transfers, payouts, ledger
ObservabilityMonitor critical pathsAlert on callback failures, signature errors, timestamp expiry, PENDING timeouts

​
Callback Implementation

  • Implement a single callback receiver endpoint
  • Verify request signature against X-GatePay-Signature
  • Check idempotency 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 callback details, see Notification & Callbacks.