1. Introduction

Through the GatePay Institution API, an institution can, with its customers’ consent, connect its own customers (such as merchants, creators, users, etc.) to GatePay, and manage those customers’ funds and transactions within a unified account system. In general, the institution first opens its own GatePay institutional account, and then uses the API to create a corresponding account in GatePay for each customer. Within the system, this account exists as a “sub-account under the institution’s account,” where the funds belong to the customer, while the account lies under the institution’s management domain.

Based on this account model, the institution can, within its own system, initiate and manage various business operations in the name of the sub-account, including but not limited to:

• Acquiring: Create orders with the sub-account as the payee so that end users can pay directly to that sub-account;
• Instant conversion / exchange: Perform currency or asset conversion within GatePay with the sub-account as the main entity;
• Payment / withdrawal: Initiate outbound or internal payments, settlements, and withdrawals with the sub-account as the payer;
• Inquiry: Query the sub-account’s balance, ledger transactions, order list, and order status information;

At the same time, GatePay provides two types of fund interfaces, charge and transfer, to enable internal fund movements within the GatePay account system:

• Between the “institutional account ↔ sub-accounts” to support platform commissions, service fee collection, periodic settlement, and fund sweeping;
• Between “sub-account ↔ sub-account” to support internal transfers and profit sharing among multiple entities and business lines;

The institution does not need to build its own underlying ledger system. Instead, it can rely on GatePay to construct profit-sharing, settlement, and fund management logic that aligns with its own business rules.

To distinguish whether a request is operating on the institution’s own account or acting on behalf of a specific sub-account, the API defines a logical parameter X-GatePay-On-Behalf-Of:

• When the request carries X-GatePay-On-Behalf-Of = <sub-account ID>, the business principal of this operation is regarded as that sub-account. Acquiring, instant conversion, payment, inquiry, and other actions will all be reflected under this sub-account;
• When the request carries X-GatePay-On-Behalf-Of as the institution’s own merchant ID, the operation is treated as being performed on the institution’s own GatePay institutional account. This is more suitable for scenarios such as fund management at the institutional level, and receiving, paying, and sweeping at the master-account level.

The following is the interaction sequence diagram:

2. API Endpoints

2.1 Accounts

2.1.1 Create Sub-Account

• API description: Create a new sub-account for a customer under the institution account and register the account holder information.

• Data type: JSON (content-type: application/json)

• HTTP method: POST

• Path: /merchant/open/institution/v1/accounts/create

• Authentication: Signature verification

• Request body:

Field Name	Type	Required	Description
request_id	string	Yes	Unique request ID from caller
customer_id	string	Yes	Customer ID on the platform side
display_name	string	Yes	Display name of the sub-account
account_holder	AccountHolder	Yes	Account holder (entity) info
metadata	map<string, object>	No	Additional key–value metadata

AccountHolder:

Field Name	Type	Required	Description
entity_country	string	Yes	Entity’s country ISO code. For the full list, refer to the official ISO online browsing platform or public ISO 3166-1 alpha-2 tables (for example, the country code list on the IBAN official website: https://www.iban.com/country-codes).
entity_type	string	Yes	Entity type: individual - INDIVIDUAL, business - BUSINESS
entity_name	string	Yes	Entity name (person’s full name / legal business name)
entity_id_type	string	Yes	ID document type, see “Document Type Enumeration”
entity_id_number	string	Yes	ID document number
entity_id_expiry	EntityIdExpiry	Yes	ID document validity period
dob	Dob	No	Date of birth; required when entity_type is INDIVIDUAL
business_registration	BusinessRegistration	No	Business registration information; can be provided when entity_type is INDIVIDUAL
address	Address	Yes	Entity address
merchant_category	string	Yes	Merchant category, see “Merchant Category Enumeration”
website	string	No	Business website
user_agreement	bool	Yes	Whether the user has signed the agreement
ubo_list	list<Ubo>	No	List of legal representative(s) and/or ultimate beneficial owner(s) (UBO). Required when entity_type is BUSINESS.

EntityIdExpiry:

Field Name	Type	Required	Description
valid_from	int64	Yes	Effective date, in milliseconds
valid_to	int64	No	Expiry date, in milliseconds

Dob:

Field Name	Type	Required	Description
year	int	Yes	4-digit year
month	int	Yes	Month, 1–12
day	int	Yes	Day of month, 1–31

BusinessRegistration:

Field Name	Type	Required	Description
reg_number	string	No	Registration number
reg_country	string	No	Country of registration
established_at	int64	No	Date of establishment

Address:

Field Name	Type	Required	Description
line1	string	Yes	Address line 1
line2	string	No	Address line 2
line3	string	No	Address line 3
country	string	Yes	Country code
city	string	No	City
state	string	No	State / province
postal_code	string	No	Postal code

Ubo:

Field Name	Type	Required	Description
country	string	Yes	Country ISO code
full_name	string	Yes	Full name of the individual
dob	Dob	Yes	Date of birth
id_type	string	Yes	Type of identification document (individual)
id_number	string	Yes	Identification document number
id_expiry	EntityIdExpiry	Yes	Expiration details of the identification document
relationship	Relationship	Yes	Relationship between the individual and the sub-merchant

Relationship：

Field Name	Type	Required	Description
is_representative	boolean	No	Whether the individual is a legal representative
is_owner	boolean	No	Whether the individual is a beneficial owner
percent_ownership	decimal	No	Required when is_owner is true; represents the ownership percentage (e.g., 30.01)

Document Type Enumeration:

Enum Value	Description	Applicable Entity
PASSPORT	Passport	Individual
NATIONAL_ID	National ID / Resident ID	Individual
DRIVING_LICENSE	Driving license	Individual
BUSINESS_LICENSE	Business license / Business registration certificate	Business
CERTIFICATE_OF_INCORPORATION	Certificate of incorporation	Business

Merchant Category Enumeration:

Enum Value	Description (Chinese)	Typical Examples
GENERAL_RETAIL	一般零售 / 综合电商	Department stores, general e-commerce platforms, grocery retail, daily goods stores
SUPERMARKET_CONVENIENCE	超市 / 便利店	Chain supermarkets, neighborhood convenience stores, fresh food chains
FASHION_AND_ACCESSORIES	服饰 / 鞋帽 / 配饰	Clothing stores, shoe shops, luggage stores, accessories shops
FOOD_AND_BEVERAGE	餐饮 / 外卖	Full-service restaurants, fast food, cafés, dessert shops, bars, food delivery platforms
DIGITAL_CONTENT_AND_SAAS	数字内容 / SaaS 服务	Online subscriptions, cloud services, online tools, audio/video subscriptions, productivity software
GAMING_AND_ENTERTAINMENT	游戏 / 文娱	Online games, mobile game top-ups, game platforms, live streaming rewards, online video entertainment
TRAVEL_AND_TICKETING	机酒 / 票务 / 旅行服务	Air tickets, hotel bookings, train/bus tickets, travel agencies, OTAs
RIDE_HAILING_AND_TRANSPORT	网约车 / 出行 / 交通	Ride-hailing platforms, bike/scooter sharing, parking payments, public transit cards
HOSPITALITY_AND_LEISURE	住宿 / 休闲 / 文旅	Hotels, homestays, attraction tickets, resorts, theme parks
EDUCATION	教育 / 培训	K12 education, vocational training, online course platforms
HEALTHCARE_AND_WELLNESS	医疗 / 健康 / 美业	Medical institutions, pharmacies, health check centers, gyms, beauty & hair salons
FINANCIAL_SERVICES	金融服务	Payment institutions, wealth management platforms, insurance, securities/brokerage services (non-virtual assets)
CRYPTO_AND_WEB3	虚拟资产 / Web3 / Crypto	Exchanges, wallet providers, DeFi gateways, NFT platforms, on-chain payment merchants
UTILITIES_AND_BILLS	生活缴费 / 公用事业	Utilities (water, electricity, gas), broadband, mobile top-ups, property fees
CHARITY_AND_NONPROFIT	慈善 / 公益组织	Charities, non-profit organizations, fundraising platforms
OTHER	其他未分类行业	Merchants that cannot be classified into any of the above categories

• Response body

Field Name	Type	Description
request_id	string	Request ID
status	string	Account status: initial - INIT, processing - PENDING, created - ACTIVE, creation failed - FAIL
created	string	Creation time (milliseconds)
customer_id	string	Customer ID on the platform side
display_name	string	Display name
account_holder	AccountHolder	Account holder (entity) information
metadata	map<string, object>	Additional key–value metadata

CURL Request

curl --location --request POST 'https://openplatform.gateapi.io/merchant/open/institution/v1/accounts/create' --header 'X-GatePay-Certificate-ClientId: 4186d0c6-6a35-55a9-8dc6-5312769dbff8' --header 'X-GatePay-On-Behalf-Of: 10002' --header 'X-GatePay-Signature: 672d5650dcc9bb22ebf25fa16c28d03c0e159d742a9176d4340a5da326d75dc8a2ec24c97fa6fc5d1533dd6e968863747e1d86a45e562cbe899f9ed7e9ca7f77' --header 'X-GatePay-Timestamp: 1672905655498' --header 'X-GatePay-Nonce: 9578' --header 'Content-Type: application/json' --data-raw '{
   "request_id":"9962354390165",
   "customer_id":"2271514627301",
   "display_name":"test5563803339",
   "account_holder":{
      "entity_name":"shandong",
      "entity_country":"AF",
      "ubo_list":[
         {
            "country":"AF",
            "full_name":"testName778",
            "dob":{
               "year":2026,
               "month":3,
               "day":3
            },
            "id_type":"DRIVING_LICENSE",
            "id_number":"130",
            "id_expiry":{
               "valid_from":1773135745000,
               "valid_to":1873135745000
            },
            "relationship":{
               "is_representative":false,
               "is_owner":false,
               "percent_ownership":"30"
            }
         }
      ],
      "entity_type":"BUSINESS",
      "entity_id_type":"BUSINESS_LICENSE",
      "entity_id_number":"abcd1234",
      "dob":{
         "year":1998,
         "month":12,
         "day":10
      },
      "address":{
         "line1":"line1",
         "country":"country"
      },
      "entity_id_expiry":{
         "valid_from":1773136302158,
         "valid_to":1773172302158
      },
      "merchant_category":"GENERAL_RETAIL",
      "user_agreement":true
   },
   "metadata":{
      "k1":"test",
      "k2":123
   }'

Response:

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "request_id": "35778162074976257",
    "status": "INIT",
    "created": 1764139242707,
    "display_name": "my test",
    "customer_id": "1234",
    "account_holder": {
      "entity_country": "AF",
      "entity_type": "BUSINESS",
      "entity_name": null,
      "entity_id_type": "BUSINESS_LICENSE",
      "entity_id_number": "abcd1234",
      "entity_id_expiry": {
        "valid_from": 1763538010509,
        "valid_to": null
      },
      "dob": null,
      "business_registration": null,
      "address": null,
      "merchant_category": "GENERAL_RETAIL",
      "website": null,
      "user_agreement": true
    },
    "metadata": null
  }
}

2.1.2 Update Sub-Account

• API Description: Update sub-account profile and account holder information.

• Data Type: JSON (content-type: application/json)

• Request Method: POST

• Path: /merchant/open/institution/v1/accounts/update

• Verification Method: Signature verification

• Request Body:

Field Name	Type	Required	Description
display_name	string	No	Sub-account display name
account_holder	AccountHolder	No	Account holder (entity) information (overwrite)
metadata	map<string, object>	No	Additional key-value pairs

• Response Body

Field Name	Type	Description
account_id	string	Sub-account ID
status	string	Account status. Initial - INIT; Processing - PENDING; Active - ACTIVE; Creation failed - FAIL.
updated	string	Update time (milliseconds)
customer_id	string	Customer ID on the platform side
display_name	string	Display name
account_holder	AccountHolder	Account holder (entity) information
metadata	map<string, object>	Additional key-value pairs

cURL Request

curl --location --request POST 'https://openplatform.gateapi.io/merchant/open/institution/v1/accounts/update' --header 'X-GatePay-Certificate-ClientId: 4186d0c6-6a35-55a9-8dc6-5312769dbff8' --header 'X-GatePay-On-Behalf-Of: 2124538349' --header 'X-GatePay-Signature: 672d5650dcc9bb22ebf25fa16c28d03c0e159d742a9176d4340a5da326d75dc8a2ec24c97fa6fc5d1533dd6e968863747e1d86a45e562cbe899f9ed7e9ca7f77' --header 'X-GatePay-Timestamp: 1672905655498' --header 'X-GatePay-Nonce: 9578' --header 'Content-Type: application/json' --data-raw '{
    "display_name": "new name",
    "account_holder":{
      "entity_name":"shandong",
      "entity_country":"AF",
      "ubo_list":[
         {
            "country":"AF",
            "full_name":"test name 778",
            "dob":{
               "year":2026,
               "month":3,
               "day":3
            },
            "id_type":"DRIVING_LICENSE",
            "id_number":"130",
            "id_expiry":{
               "valid_from":1773135745000,
               "valid_to":1873135745000
            },
            "relationship":{
               "is_representative":false,
               "is_owner":false,
               "percent_ownership":"30"
            }
         }
      ],
      "entity_type":"BUSINESS",
      "entity_id_type":"BUSINESS_LICENSE",
      "entity_id_number":"abcd1234",
      "dob":{
         "year":1998,
         "month":12,
         "day":10
      },
      "address":{
         "line1":"line1",
         "country":"country"
      },
      "entity_id_expiry":{
         "valid_from":1773136302158,
         "valid_to":1773172302158
      },
      "merchant_category":"GENERAL_RETAIL",
      "user_agreement":true
   }
}'

Response:

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "status": "ACTIVE",
    "updated": 1764141615061,
    "display_name": "new name",
    "customer_id": "1234",
    "account_id": "2124538349",
    "account_holder": {
      "entity_country": "AF",
      "entity_type": "BUSINESS",
      "entity_name": null,
      "entity_id_type": "BUSINESS_LICENSE",
      "entity_id_number": "abcd1234",
      "entity_id_expiry": {
        "valid_from": 1763538010509,
        "valid_to": null
      },
      "dob": null,
      "business_registration": null,
      "address": null,
      "merchant_category": "GENERAL_RETAIL",
      "website": null,
      "user_agreement": true
    },
    "metadata": null
  }
}

2.1.3 Query Sub-Account

• API Description: Query sub-account details.

• Data Type: JSON (content-type: application/json)

• Request Method: GET

• Path: /merchant/open/institution/v1/accounts/query

• Verification Method: Signature verification

• Request Parameters:

Field Name	Type	Required	Description
request_id	string	No	Creation request ID
account_id	string	No	Sub-account ID

• Response Body

Field Name	Type	Description
request_id	string	Creation request ID
account_id	string	Sub-account ID
customer_id	string	Customer ID on the platform side
display_name	string	Display name
status	string	Account status. Initial - INIT; Processing - PENDING; Active - ACTIVE; Creation failed - FAIL.
created	int64	Creation time (milliseconds)
updated	int64	Update time (milliseconds)
account_holder	AccountHolder	Account holder (entity) information
metadata	map<string, object>	Additional key-value pairs

cURL Request

curl --location --request GET 'https://openplatform.gateapi.io/merchant/open/institution/v1/accounts/query?request_id=35778162074976257' --header 'X-GatePay-Certificate-ClientId: aTEPWRmyiaBapQUb' --header 'X-GatePay-On-Behalf-Of: 10002' --header 'X-GatePay-Timestamp: 1763359927439' --header 'X-GatePay-Nonce: 8936028189' --header 'X-GatePay-Signature: 5277b95af7aaa506ed9336ddc1b08fc63d5e4106577f3852453d87c2010230b55cffc15d417c35ca7b1fb9016e9143be4c6e1c5c281d82795b79fe075e313f13' --header 'Content-Type: application/json' ```

Response:

```json
{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "request_id": "35778162074976257",
    "account_id": "2124538349",
    "customer_id": "1234",
    "display_name": "new name",
    "status": "ACTIVE",
    "created": 1763469689743,
    "updated": 1764141615061,
    "account_holder": {
      "entity_country": "AF",
      "entity_type": "BUSINESS",
      "entity_name": null,
      "entity_id_type": "BUSINESS_LICENSE",
      "entity_id_number": "abcd1234",
      "entity_id_expiry": {
        "valid_from": 1763538010509,
        "valid_to": null
      },
      "dob": null,
      "business_registration": null,
      "address": null,
      "merchant_category": "GENERAL_RETAIL",
      "website": null,
      "user_agreement": true
    },
    "metadata": null
  }
}

2.1.4 List Sub-Accounts (Paginated)

• API Description: List sub-accounts with pagination.

• Data Type: JSON (content-type: application/json)

• Request Method: GET

• Path: /merchant/open/institution/v1/accounts/list

• Verification Method: Signature verification

• Request Parameters:

Field Name	Type	Required	Description
status	string	No	Status. Active - ACTIVE.
request_id	string	No	Creation request ID
customer_id	string	No	Customer ID on the platform side
created_gte	int64	No	Creation time timestamp in milliseconds, greater than or equal to this value
created_lte	int64	No	Creation time timestamp in milliseconds, less than or equal to this value
limit	int	No	Page size. Default 20, maximum 200
cursor	int	No	Page number, starting from 1

• Response Body

Field Name	Type	Description
accounts	[]AccountInfo	Sub-account list
has_more	bool	Whether there is a next page

AccountInfo:

Field Name	Type	Description
request_id	string	Creation request ID
account_id	string	Sub-account ID
customer_id	string	Customer ID on the platform side
display_name	string	Display name
status	string	Account status. Initial - INIT; Processing - PENDING; Active - ACTIVE; Creation failed - FAIL.
created	int64	Creation time (milliseconds)

cURL Request

curl --location --request GET 'https://openplatform.gateapi.io/merchant/open/institution/v1/accounts/list?cursor=1&limit=20&request_id=35778162074976257' --header 'X-GatePay-Certificate-ClientId: aTEPWRmyiaBapQUb' --header 'X-GatePay-On-Behalf-Of: 10002' --header 'X-GatePay-Timestamp: 1763359927439' --header 'X-GatePay-Nonce: 8936028189' --header 'X-GatePay-Signature: 5277b95af7aaa506ed9336ddc1b08fc63d5e4106577f3852453d87c2010230b55cffc15d417c35ca7b1fb9016e9143be4c6e1c5c281d82795b79fe075e313f13' --header 'Content-Type: application/json' ```

Response:

```json
{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "accounts": [
      {
        "request_id": "35778162074976257",
        "account_id": "2124543768",
        "customer_id": "1234",
        "display_name": "my test",
        "status": "ACTIVE",
        "created": 1764139266551
      }
    ],
    "has_more": false
  }
}

2.1.5 Callback Notification

Sub-account creation success notification:

Field Name	Type	Description
bizType	string	Notification category. INSTITUTION - sub-account creation
bizId	string	Creation request ID
bizStatus	string	Business status. INSTITUTION_ACCOUNT_SUCCESS - creation succeeded; INSTITUTION_ACCOUNT_FAIL - creation failed
client_id	string	Merchant client_id that created the sub-account
data	content	Message payload, JSON string

content:

Field Name	Type	Description
request_id	string	Creation request ID
account_id	string	Sub-account ID
customer_id	string	Customer ID on the platform side
display_name	string	Display name
status	string	Account status. Active - ACTIVE; Creation failed - FAIL.
created	int64	Creation time (milliseconds)

Example of sub-account creation success notification:

{
  "bizType": "INSTITUTION",
  "bizId": "35778162074976257",
  "bizStatus": "INSTITUTION_ACCOUNT_SUCCESS",
  "clientId": "ktBVqBBHrEHJmfZH",
  "data": "{"request_id":"35778162074976257","account_id":"2124543768","customer_id":"1234","display_name":"my test","status":"ACTIVE","created":1764139242707}"
}

Message payload:

{
  "request_id": "35778162074976257",
  "account_id": "2124543768",
  "customer_id": "1234",
  "display_name": "my test",
  "status": "ACTIVE",
  "created": 1764139242707
}

2.2 Finance

2.2.1 Get Account Balance

• API Description: Query account balance details

• Data Type: JSON (content-type: application/json)

• HTTP Method: POST

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Request Path: /payment/open/institution/v1/balance

• Authentication: Signature verification

• Request Body: ["currency1", "currency2"]

• Response Body:

  Field Name	Type	Description
  balanceList	array	List of balances for the requested currencies.

• Request Example:

curl --location 'http://openplatform.gateapi.io/payment/open/institution/v1/balance' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp: {{X_GatePay_Timestamp}}' --header 'X-GatePay-Nonce: {{nonce}}' --header 'X-GatePay-Signature: {{sign}}' --header 'X-GatePay-On-Behalf-Of: 2124538349' --header 'Content-Type: application/json' --data '["USDT","BTC"]'

{
  "code": "000000",
  "data": {
    "balanceList": [
      {
        "currency": "BTC",
        "available": "0.01"
      },
      {
        "currency": "USDT",
        "available": "12.34411"
      }
    ]
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.2.2 Retrieve Transaction History

• Data Type：JSON （content-type：application/json）

• Method：GET

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /payment/open/institution/v1/pay/bill/orderlist

• Verification Method: Signature Verification

• Request Content:

Field Name	Type	Is Required	Description
startTime	int64	Y	Start time in milliseconds
endTime	int64	Y	End time in milliseconds
page	int	Y	Page number, starting from 1
count	int	Y	Number of records per page, up to 500
currency	string	N	Currency to search
financialType	string	N	Refers to the type of financial transaction. Includes: receipt_fi (receipt), payment_fi (payment), giftCard_fi (gift card), reward_fi (reward), distribution_fi (distribution/withdrawal), refund_fi (refund), transfer_fi (transfer), c2cTransfer_fi (P2P transfer), convert_buy_fi (convert buy), convert_sell_fi (convert sell), convert_refund_fi (convert refund), otcRecharge_add_fi (fiat deposit), otcWithdraw_fi (fiat withdrawal), interest_fi(Financial management dividends) and others_fi (others).
orderType	int	N	Order type to query: 1-Merchant order ID 2-GatePay order ID 3-Transaction history order ID
orderIdNo	string	N	Order ID to query

• Response Content

Field Name	Type	Description
total	int	Total number of records
hasNext	bool	Indicates whether there is a next page: true: YES false: NO
nextPage	int	Next page number; valid only when hasNext is true
balance_history_item_list	array	List of records returned (array)
merchant_id	int	Merchant ID

• balance_history_item_list—Response Field Definition:

Field Name	Type	Description
transactId	string	Payment ID
transactTime	int64	Posting time, in milliseconds (timestamp)
orderId	string	GatePay order ID
merchantTradeNo	string	Merchant order ID
financialType	string	Financial type
payAmount	string	Transaction amount (inflow or outflow)
currency	string	Currency of the transaction amount
balance	string	Account balance
balanceCurrency	string	Currency of the account balance
status	string	Order status; PAID indicates success
payer	Int64	Payer UID in Gate Pay
buyer	string	For Web3 payments, this is the payment address; for non-Web3 payments, this is the payer's UID.
refund_gate_id	string	Refund order ID
payChannel	string	Payment method: Web3 payment Gate Pay
fullChain	string	Full name of the payment network
address	string	Merchant receiving address
hash	string	Transaction hash

Request Example:

CURL Request:

curl --location 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/bill/orderlist?startTime=1746758276000&endTime=1746772913000&count=3&page=3' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1738934053475' \
--header 'x-GatePay-Nonce: 5417061546' \
--header 'x-GatePay-Signature: b8c4705ff4c1357f2a27925dd180c1e1f4a244148f312a2dee5afbcc6f4b150e9ffceee455c5a298f895d43a64ee829eebdfd262539d45c41f7aee4336fd8c8c' \
--header 'X-GatePay-On-Behalf-Of: 10002' 

Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "merchant_id": 10002,
        "total": 18,
        "hasNext": true,
        "nextPage": 4,
        "balance_history_item_list": [
            {
                "transactId": "355711415868440576",
                "transactTime": 1746769810346,
                "orderId": "355450733498011648",
                "merchantTradeNo": "1746707644001",
                "financialType": "refund_fi",
                "payAmount": "-1",
                "currency": "USDT",
                "Balance": "934183.9783514209",
                "BalanceCurrency": "USDT",
                "status": "PAID",
                "payer": 10002,
                "buyer": "",
                "fullChain": "",
                "hash": "",
                "address": "TMB5f9CgcnYR365knMXKrMM6aGoYpphquj",
                "payChannel": "mini_pay",
                "refund_gate_id": "13411853592035330"
            },
            {
                "transactId": "355711310076907520",
                "transactTime": 1746769785136,
                "orderId": "355450733498011648",
                "merchantTradeNo": "1746707644001",
                "financialType": "refund_fi",
                "payAmount": "+1",
                "currency": "USDT",
                "Balance": "934184.9783514209",
                "BalanceCurrency": "USDT",
                "status": "PAID",
                "payer": 10002,
                "buyer": "",
                "fullChain": "",
                "hash": "",
                "address": "TMB5f9CgcnYR365knMXKrMM6aGoYpphquj",
                "payChannel": "mini_pay",
                "refund_gate_id": "13411849297068033"
            },
            {
                "transactId": "355711310076907520",
                "transactTime": 1746769785131,
                "orderId": "355450733498011648",
                "merchantTradeNo": "1746707644001",
                "financialType": "refund_fi",
                "payAmount": "-1",
                "currency": "USDT",
                "Balance": "934183.9783514209",
                "BalanceCurrency": "USDT",
                "status": "PAID",
                "payer": 10002,
                "buyer": "",
                "fullChain": "",
                "hash": "",
                "address": "TMB5f9CgcnYR365knMXKrMM6aGoYpphquj",
                "payChannel": "mini_pay",
                "refund_gate_id": "13411849297068033"
            }
        ]
    }
}

2.3 Orders

2.3.1 Checkout Order

• API Description: Create a checkout (cashier) order

• Data Type: JSON (content-type: application/json)

• HTTP Method: POST

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Request Path: /payment/open/institution/v1/pay/checkout/order

• Authentication: Signature verification

• Request Body:

Field Name	Type	Required	Description
merchantTradeNo	string	Yes	Merchant order number.
currency	string	Yes	Order currency in uppercase, e.g. USDT, BTC.
orderAmount	string	Yes	Order amount. Minimum value is 0.000001, with up to 6 decimal places.
surchargeAmount	string	No	Surcharge, a fee borne by the consumer.
toleranceAmount	string	No	Tolerance Amount：If the remaining unpaid amount is less than or equal to the configured tolerance amount, the order will be automatically marked as Paid, with no further payment required.
fiatCurrency	string	No	Fiat order currency in uppercase form, such as EUR, GBP, USD, CNY, JPY, AUD, CAD, CHF.
fiatAmount	string	No	Fiat order amount, with a maximum precision of 2 digits.
payCurrency	string	No	Payment currency for address payment. If omitted, it defaults to the same value as currency.
env	Env type	Yes	Transaction source.
goods	goods type	Yes	Product information.
orderExpireTime	int64	No	Absolute expiration time in milliseconds. If not set, defaults to 1 hour; the maximum expiration time is 1 hour.
returnUrl	string	No	Redirect URL after successful payment. Maximum length: 256 characters.
cancelUrl	string	No	Redirect URL after payment failure. Maximum length: 256 characters.
merchantUserId	int64	Yes	Unique ID of the payer when registered on the merchant platform.
chain	string	Yes	Name of the selected chain. The merchant can call /v1/pay/address/chains to obtain available values; see the Address Payment documentation.
fullCurrType	string	Yes	Currency field including the chain, mapping to a specific currency on a specific chain.
channelId	string	No	Customer name.

Env type

Field Name	Type	Required	Description
terminalType	string	Yes	Transaction source. Allowed values: APP, WEB, WAP, MINIAPP, OTHERS.

Goods type

Field Name	Type	Required	Description
goodsName	string	Yes	Product name, maximum length 160 characters.
goodsDetail	string	No	Product description, maximum length 256 characters.
goodsType	string	No	Product category.

Response Body:

Field Name	Type	Required	Description
status	string	Yes	SUCCESS or FAIL.
code	string	Yes	Error code.
data	data type	No	Order information.
errorMessage	string	No	Error message.

Data structure:

Field Name	Type	Description
prepayId	string	ID of the created pre-order.
currency	string	Crypto Order currency.
orderAmount	string	Order Amount.
surchargeAmount	string	Surcharge, a fee borne by the consumer.
toleranceAmount	string	Tolerance Amount：If the remaining unpaid amount is less than or equal to the configured tolerance amount, the order will be automatically marked as Paid, with no further payment required.
fiatCurrency	string	Fiat order currency.
fiatAmount	string	Fiat order amount.
terminalType	string	Transaction source. Allowed values: APP, WEB, WAP, MINIAPP, OTHERS.
expireTime	int64	Order expiration time, UTC timestamp in milliseconds. If not set, defaults to 1 hour; the maximum expiration time is 1 hour.
qrContent	string	Order QR content in URL format. The developer must generate the QR code image based on this content.
location	string	Redirect URL to invoke the checkout page after order is created successfully.
payCurrency	string	Payment currency for address payment.
payAmount	string	Payment amount for address payment.
chain	chain type	Chain information for address payment.
goodsName	string	Product name.
inUsdt	string	Amount converted to USDT.

Chain type

Field Name	Type	Description
chain_type	string	Chain name.
address	string	Receiving address on the specified chain bound to the order.
fullCurrType	string	Currency field including the chain, mapping to a specific currency on a specific chain.

Request Example:

curl --location 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/checkout/order' --header 'Content-Type: application/json' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp: 1695611256106' --header 'X-GatePay-Nonce: 1260554069' --header 'X-GatePay-On-Behalf-Of: 2124538349' --header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' --data '{
  "merchantTradeNo": "163",
  "env": {
    "terminalType": "APP"
  },
  "currency": "USDT",
  "orderAmount": "118.75",
  "merchantUserId": 123,
  "goods": {
    "goodsType": "02",
    "goodsName": "Sipariş Ödemesi - 177",
    "goodsDetail": "Sipariş No : 160"
  },
  "returnUrl": "https://lotkeys.com/tr/gate-payment-response",
  "cancelUrl": "https://lotkeys.com/tr/gate-payment-response",
  "chain": "MATIC",
  "fullCurrType": "USDT_MATIC",
  "channelId": "123456"
}'

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "prepayId": "65466648727916544",
    "currency": "USDT",
    "orderAmount": "118.75",
    "surchargeAmount": "0",
    "fiatCurrency": "",
    "fiatAmount": "",
    "terminalType": "APP",
    "expireTime": 1677573665219,
    "qrContent": "http://openplatform.gate.io/qr/GA0cskPehKxQpshvm3Goeve8dHpwCl6yCHLSWUYrLqo=",
    "location": "https://www.gate.com/cashier?prepayid=65466648727916544",
    "payCurrency": "USDT",
    "payAmount": "118.75",
    "chain": {
      "chain_type": "BSC",
      "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
      "fullCurrType": "USDT_EOS"
    },
    "channelId": "123456",
    "goodsName": "Sipariş Ödemesi - 177",
    "inUsdt": "118.75"
  }
}

2.3.2 Address Order

• API Description: Create an address order

• Data Type: JSON (content-type: application/json)

• HTTP Method: POST

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Request Path: /payment/open/institution/v1/pay/address/create

• Authentication: Signature verification

• Request Body:

Field Name	Type	Required	Description
merchantTradeNo	string	Yes	Transaction ID in the merchant system.
currency	string	Yes	Order currency.
orderAmount	string	Yes	Order amount.
surchargeAmount	string	No	Surcharge, a fee borne by the consumer.
toleranceAmount	string	No	Tolerance Amount：If the remaining unpaid amount is less than or equal to the configured tolerance amount, the order will be automatically marked as Paid, with no further payment required.
fiatCurrency	string	No	Fiat order currency in uppercase form, such as EUR, GBP, USD, CNY, JPY, AUD, CAD, CHF.
fiatAmount	string	No	Fiat order amount, with a maximum precision of 2 digits.
payCurrency	string	No	User-selected payment currency. Not required for non-swap (non-conversion) orders.
env	EnvRequest	Yes	Transaction source. Allowed values: APP, WEB, WAP, MINIAPP, OTHERS.
goods	GoodsRequest	Yes	Product information.
orderExpireTime	int64	Yes	Order expiration timestamp in milliseconds, specified by the merchant.
returnUrl	string	No	Callback URL after payment completion.
cancelUrl	string	No	Callback URL after payment cancellation.
merchantUserId	int64	Yes	Unique ID of the payer when registered on the merchant platform.
chain	string	Yes	Name of the selected chain.
fullCurrType	string	Yes	Currency field including the chain, mapping to a specific currency on a specific chain.
channelId	string	No	Customer name.

EnvRequest

Field Name	Type	Required	Description
terminalType	string	Yes	Terminal type creating the order.

GoodsRequest

Field Name	Type	Required	Description
goodsName	string	No	Product name.
goodsDetail	string	No	Product details.

Response Body:

Field Name	Type	Description
prepayId	string	Created payment order ID.
terminalType	string	Terminal type that created the order.
expireTime	string	Expiration timestamp in milliseconds.
chain	Chain	Chain and address bound to the payment order.

Chain

Field Name	Type	Description
chain_type	string	Chain name.
address	string	Receiving address on the chain bound to the order.
fullCurrType	string	Currency field including the chain.

Request Example:

curl --location --request POST 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create' --header 'Content-Type: application/json' --header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' --header 'X-GatePay-Timestamp: 1673323831902' --header 'X-GatePay-Nonce: 6225572445' --header 'X-GatePay-On-Behalf-Of: 2124538349' --header 'X-GatePay-Signature: 8be2d2efcd59354067cfcde2a38ce5921a0ccf39855331971d0855f79fc7e5218782319e0615559a38c9a95b9e9cd6d6de4b3f4e04a8f81458542c369cef5f10' --data-raw '{
  "merchantTradeNo": "93840202212210025",
  "currency": "BTC",
  "orderAmount": "2.1",
  "env": {
    "terminalType": "MINIAPP"
  },
  "goods": {
    "goodsName": "USDT_PAY_BTC_TEST",
    "goodsDetail": "yc"
  },
  "orderExpireTime": 1673410179000,
  "returnUrl": "www.test1.com",
  "cancelUrl": "www.test2.com",
  "merchantUserId": 1336974,
  "chain": "BSC",
  "fullCurrType": "BTC_BSC",
  "channelId": "123456"
}'

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "prepayId": "47656656276819968",
    "terminalType": "MINIAPP",
    "expireTime": 1673410179000,
    "chain": {
      "chain_type": "BSC",
      "fullCurrType": "USDT_BSC",
      "address": "0x1699dB45Dc502A0395038265fCBC4Fa05d6afFBD"
    }
  }
}

2.3.3 Web / QR-Code Orders

• API Description: Create a web or QR-code pending payment order

• Data type: JSON (content-type: application/json)

• Request method: POST

• Request header:

  Field	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant portal
  X-GatePay-Timestamp	string	Yes	UTC timestamp at the time the request is generated, in milliseconds. GatePay will not process requests whose time difference exceeds 10 seconds
  X-GatePay-Nonce	string	Yes	Random string. Must conform to HTTP header specifications. Recommended length ≤ 32 characters, consisting of digits and letters
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account being acted on
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid

• Path: /payment/open/institution/v1/pay/transactions/native

• Authentication: Signature verification

• Request body:

Field	Type	Required	Description
merchantTradeNo	string	Yes	Merchant order number, no longer than 32 bytes
currency	string	No	Order currency, in uppercase, such as USDT, BTC, etc.
orderAmount	string	No	Order amount. Range: [0.0001, 500000]
fiatCurrency	string	No	Fiat order currency in uppercase form, such as EUR, GBP, USD, CNY, JPY, AUD, CAD, CHF.
fiatAmount	string	No	Fiat order amount, with a maximum precision of 2 digits.
actualCurrency	string	No	Actual settlement currency required by the merchant. If the settlement currency is different from the order currency, specify it here
env	Env type	Yes	Transaction source: APP, WEB, WAP, MINIAPP, OTHERS
goods	goods type	Yes	Goods information
orderExpireTime	int64	No	Order expiration time, UTC timestamp in milliseconds. Default is 1 hour if not set. Maximum expiration time is 1 hour
returnUrl	string	No	URL to redirect to after successful payment. Maximum length: 256 characters
cancelUrl	string	No	URL to redirect to after failed payment. Maximum length: 256 characters
channelId	string	No	Customer name

Env type

Field	Type	Required	Description
terminalType	string	Yes	Transaction source. Valid values: APP, WEB, WAP, MINIAPP, OTHERS

Goods type

Field	Type	Required	Description
goodsName	string	Yes	Goods name, maximum length 160 characters
goodsDetail	string	No	Goods description, maximum length 256 characters

• Response body:

Field	Type	Required	Description
status	string	Yes	SUCCESS or FAIL
code	string	Yes	Error code
data	data type	No	Refund order information
errorMessage	string	No	Error message

Fields in data:

Field	Type	Required	Description
prepayId	string	Yes	ID of the created pre-order
terminalType	string	Yes	Transaction source. Valid values: APP, WEB, WAP, MINIAPP, OTHERS
expireTime	int64	Yes	Order expiration time, in milliseconds. Default is 1 hour if not set. Maximum expiration time is 1 hour
qrContent	string	Yes	QR code content in URL format. The developer needs to generate the QR image based on this content
location	string	Yes	Redirect URL of the web payment component after the order is created

Request example:

curl --location --request POST 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/transactions/native' --header 'Content-Type: application/json' --header 'X-GatePay-Certificate-ClientId: zb6WUrBDZlRAT7qz' --header 'X-GatePay-Timestamp: 1674117221032' --header 'x-GatePay-Nonce: 7436636664' --header 'x-GatePay-Signature: 11e658cf6b09d917caf9d4bb6ec4493431c55f066a694e58a5571a4a1a114ebc2011d346f340e54a5a2e2edaa172e907742fbdc99b94d009dade4b551daabd07' --data-raw '{
    "MerchantTradeNo": "118223456797",
    "currency":"USDT",
    "orderAmount":"1.9",
    "env": {
        "terminalType": "APP"
    },
    "goods": {
            "goodsName": "NF2T",
            "goodsDetail": "nef-book"
    },
    "orderExpireTime":1674118228000,
    "returnUrl":"http://47.99.158.63:8205/payment/callback",
    "channelId":"123456"
}'

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "50984376880599040",
        "terminalType": "APP",
        "expireTime": 1674118228000,
        "location": "https://www.gate.io/webpay?prepayid=55583289224171652",
        "qrContent": "http://openplatform.gate.io/qr/amaA9duknMfGKvM5H77Q0STgoTgVPmbPyuPDzlFvJO8="
    }
}

2.3.4 Query Order Details

• API Description: Query order details

• Data type: JSON (content-type: application/json)

• Request method: POST

• Request header:

  Field	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant portal
  X-GatePay-Timestamp	string	Yes	UTC timestamp at the time the request is generated, in milliseconds. GatePay will not process requests whose time difference exceeds 10 seconds
  X-GatePay-Nonce	string	Yes	Random string. Must conform to HTTP header specifications. Recommended length ≤ 32 characters, consisting of digits and letters
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account being acted on
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid

• Path: /payment/open/institution/v1/pay/order/query

• Authentication: Signature verification

• Request body:

Field	Type	Required	Description
prepayId	string	No	Pre-order ID
merchantTradeNo	string	No	Merchant order ID. Either prepayId or this field is required

• Response body:

Field	Type	Required	Description
status	string	Yes	SUCCESS or FAIL
code	string	Yes	Error code
data	query order return type	No	Payment order information
errorMessage	string	No	Error message

Fields in data:

Field	Type	Required	Description
prepayId	string	Yes	Pre-order ID
merchantId	int64	Yes	Gate UID used when applying for the merchant account
merchantTradeNo	string	Yes	Merchant order number
transactionId	string	Yes	Transaction ID
goodsName	string	Yes	Goods name
currency	string	Yes	Order currency
orderAmount	string	Yes	Order amount
toleranceAmount	string	No	Tolerance Amount：If the remaining unpaid amount is less than or equal to the configured tolerance amount, the order will be automatically marked as Paid, with no further payment required.
underpaidAmount	string	No	After payment is completed, the remaining payment amount
surchargeAmount	string	No	Surcharge, a fee borne by the consumer.
fiatCurrency	string	No	Fiat order currency.
fiatAmount	string	No	Fiat order amount.
fiatRate	string	No	Fiat rate.
status	string	Yes	Order status
createTime	int64	Yes	Pre-order creation time, in milliseconds
expireTime	int64	Yes	Pre-order expiration time, in milliseconds
transactTime	int64	Yes	Payment completion time, in milliseconds
order_name	string	Yes	Order name
pay_currency	string	Yes	Currency actually paid by the user
pay_amount	string	Yes	Amount actually paid by the user
expectCurrency	string	No	Revenue currency specified by the merchant when creating the order. Returned only for orders with specified settlement currency
actualCurrency	string	No	Currency actually settled to the merchant account in Gate backend after payment completion. Returned only after Gate has settled the order
actualAmount	string	No	Amount actually settled to the merchant account in the corresponding actualCurrency. Returned only after Gate has settled the order
rate	string	Yes	Exchange rate for instant-exchange payments
channelId	string	No	Customer name
appName	string	No	Application name
appLogo	string	No	Application logo URL
inUsdt	string	No	Equivalent amount in USDT
channel_type	string	No	Channel type

Request example

curl -X POST -H "Content-Type:application/json"         -H "X-GatePay-Certificate-ClientId: aa721ba2-5bad-55e5-b3f9-43f9cbe6d814"         -H "x-gateio-payment-timestamp: 1647556285603"         -H "x-gateio-payment-nonce: OBBHcyeIQn"         -H 'X-GatePay-On-Behalf-Of: 2124538349'         -H "x-gateio-payment-signature: 1f020e1ee70a7ced14de42f4293592d43f8a74eab5ba4c3771dc6d215278d889fd0ecd398c1026a003b1351752b34c24cd8288afa7ff7552ca06a2aea992a897"         -d '{"merchantTradeNo": "56236"}' https://openplatform.gateapi.io/payment/open/institution/v1/pay/order/query

Query order details without specified revenue currency – response example:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "50620368071692288",
        "merchantId": 10002,
        "merchantTradeNo": "4379824792349592345",
        "transactionId": "",
        "goodsName": "NFT",
        "currency": "GT",
        "orderAmount": "0.1",
        "fiatCurrency": "",
        "fiatAmount": "",   
        "fiatRate": "", 
        "status": "EXPIRED",
        "createTime": 1674030436229,
        "expireTime": 1663054706000,
        "transactTime": 0,
        "order_name": "MiniApp-Payment#4379824792349592345",
        "pay_currency": "",
        "pay_amount": "0",
        "rate": "0",
        "channel_type": "",
        "inUsdt": "",
        "appLogo": "https://gimg2.gateimg.com/image/432c2715a0eaa6217af7a3db1e85ffc8dc866233.webp",
        "appName": "Latiago",
        "channelId":"123456"
    }
}

Query order details with specified revenue currency, not settled yet – response example:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "56335302571069440",
        "merchantId": 10002,
        "merchantTradeNo": "118223456798",
        "transactionId": "",
        "goodsName": "NF2T",
        "currency": "USDT",
        "orderAmount": "1.9",
        "fiatCurrency": "",
        "fiatAmount": "",
        "fiatRate": "",
        "status": "EXPIRED",
        "createTime": 1675392982792,
        "expireTime": 1675396480000,
        "transactTime": 0,
        "order_name": "MiniApp-Payment#118223456798",
        "pay_currency": "",
        "pay_amount": "0",
        "expectCurrency": "BTC",
        "channel_type": "",
        "inUsdt": "",
        "appLogo": "https://gimg2.gateimg.com/image/432c2715a0eaa6217af7a3db1e85ffc8dc866233.webp",
        "appName": "Latiago",
        "rate": "0"
    }
}

Query order details with specified revenue currency, already settled – response example:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "56416503889661952",
        "merchantId": 10002,
        "merchantTradeNo": "1182234567119",
        "transactionId": "56416503889661952",
        "goodsName": "NF2T",
        "currency": "GT",
        "orderAmount": "1",
        "fiatCurrency": "",
        "fiatAmount": "",
        "fiatRate": "",
        "status": "PAID",
        "createTime": 1675412342695,
        "expireTime": 1675414420000,
        "transactTime": 1675412385904,
        "order_name": "MiniApp-Payment#1182234567119",
        "pay_currency": "BTC",
        "pay_amount": "1",
        "expectCurrency": "USDT",
        "actualCurrency": "USDT",
        "actualAmount": "1",
        "rate": "1",
        "channel_type": "",
        "inUsdt": "",
        "appLogo": "https://gimg2.gateimg.com/image/432c2715a0eaa6217af7a3db1e85ffc8dc866233.webp",
        "appName": "Latiago",
        "channelId":"123456"
    }
}

2.3.5 Cancel Order

• API Description: Cancel an order

• Data type: JSON (content-type: application/json)

• Request method: POST

• Request header:

  Field	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant portal
  X-GatePay-Timestamp	string	Yes	UTC timestamp at the time the request is generated, in milliseconds. GatePay will not process requests whose time difference exceeds 10 seconds
  X-GatePay-Nonce	string	Yes	Random string. Must conform to HTTP header specifications. Recommended length ≤ 32 characters, consisting of digits and letters
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account being acted on
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid

• Path: /payment/open/institution/v1/pay/order/close

• Authentication: Signature verification

• Request body:

Field	Type	Required	Description
merchantTradeNo	string	No	Merchant order number, no longer than 32 bytes
prepayId	string	No	prepayId. Only one of prepayId or merchantTradeNo is required

• Response body:

Field	Type	Required	Description
status	string	Yes	SUCCESS or FAIL
code	string	Yes	Error code
data	close result type	Yes	Close result
errorMessage	string	No	Error message

close result type

Field	Type	Required	Description
result	string	Yes	SUCCESS or FAIL

Request example

curl --location 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/order/close' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp: {{X_GatePay_Timestamp}}' --header 'X-GatePay-Nonce: {{nonce}}' --header 'X-GatePay-Signature: {{sign}}' --header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' --header 'Content-Type: application/json' --header 'Accept: */*' --header 'Cache-Control: no-cache' --header 'Host: openplatform.gateapi.io' --header 'Connection: keep-alive' --header 'X-GatePay-On-Behalf-Of: 2124538349' --data '{"prepayId":"35771760426090520"}'

{
    "status": "SUCCESS",
    "code": "000000",
    "data": {
        "result": "SUCCESS"
    },
    "errorMessage": ""
}

2.3.6 Query Supported Networks and Currencies

• API Description: Query supported networks and currencies

• Data Type: JSON （content-type：application/json）

• Request Method: GET

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /merchant/open/institution/v1/pay/fixedaddress/chains

• Validation Method: Merchant signature verification

Interface Description:

Queries the networks and currencies supported by GatePay for static address collection.

Request Parameters:

None

Response Parameters:

Field Name	Type	Description
Chains	[]*FixedChainItem	List of supported networks and currencies

FixedChainItem

Field Name	Type	Description
chain	string	Network
showChainNameEn	string	Network English name
currencies	string	Currencies supported under this network

Request Example

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/pay/fixedaddress/chains' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727244774062' \
--header 'X-GatePay-Nonce: 6528576972' \
--header 'X-GatePay-Signature: 6bb0a23cf2f397ab4e602e3dc9d04cad59d265fdfe621bbf978409c6c705f86092c6ac5251c0d349dc93e5fbcf9d6ba2e2beae928d3a01ef72ba9ef8581172e5' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'

Response Example

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "Chains": [
            {
                "chain": "ETH",
                "showChainNameEn": "ETH/ERC20",
                "currencies": [
                    "USDT",
                    "DAI",
                    "ETH",
                    "MATIC",
                    "USDC"
                ]
            },
            {
                "chain": "TRX",
                "showChainNameEn": "Tron/TRC20",
                "currencies": [
                    "USDT"
                ]
            }
        ]
    }
}

2.3.7 Create Static Collection Address

• API Description: Create static collection address

• Data Type: JSON （content-type：application/json）

• Request Method: POST

• Request Headers:

Field Name	Type	Required	Description
X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /merchant/open/institution/v1/pay/fixedaddress/save

• Validation Method: Merchant signature verification

Interface Description:

Generates a static collection address based on the specified currency and network.

Note: If a static collection address already exists forchannelId + chain, the currencies and callbackUrl in the request will update the existing bound information.

Request Parameters:

Field Name	Type	Required	Description
channelId	string	Yes	Merchant channel ID, supports only letters, numbers, underscores, and hyphens, with a maximum length of 50 bytes
chain	string	Yes	Network name
currencies	string	Yes	Currencies to be earned at this static address, separated by commas (e.g., USDT,BTC
callbackUrl	string	Yes	Callback URL for this channel, with a maximum length of 128 bytes

Response Parameters:

Field Name	Type	Description
channelId	string	Merchant channel ID
chain	string	Network name
address	string	Collection address
currencies	[]string	List of supported currencies for this network
callbackUrl	string	Callback URL for collection notifications
desc	string	Description
ChainShowEn	string	The English name of chain

Request Example

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/pay/fixedaddress/save' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727602580817' \
--header 'X-GatePay-Nonce: 9167310285' \
--header 'X-GatePay-Signature: a23f55ded2e938fd7b6cd436837b21ec8fd413f3dbd496cffae3bedac3a41c7bf684ca46a25484f8b1607d90313ff46aff2d5b75765ef1d97f51bc63f8e0c139' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--data '{
    "channelId": "smart_shop",
    "chain": "ETH",
    "currencies": "DAI,USDT",
    "callbackUrl": "https://www.abc.com/callback"
}'

Response Example

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "channelId": "smart_shop",
    "chain": "ETH",
    "address": "0x2EBa11a702F1d53c6e2F08278819e26E6e4a63ae",
    "currencies": [
      "DAI",
      "USDT"
    ],
    "callbackUrl": "https://www.abc.com/callback",
    "desc": "",
    "ChainShowEn": "ETH /ERC20"
  }
}

2.3.8 Query Static Collection Address List

• API Description: Query static collection address list

• Data Type: JSON （content-type：application/json）

• Request Method: GET

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /merchant/open/institution/v1/pay/fixedaddress/list

• Validation Method: Merchant signature verification

Interface Description:

Queries the list of generated and valid static collection addresses.

Request Parameters:

Field Name	Type	Required	Description
page	int	Yes	A non-negative integer starting from 0, indicating the page number
count	int	Yes	A positive integer representing the number of entries displayed per page, with a maximum of 100

Response Parameters:

Field Name	Type	Description
total	int	Total amount
list	[]*FixedAddressItem	Fixed collection address list

FixedAddressItem

Field Name	Type	Description
channelId	string	Merchant channel ID
chain	string	Network
address	string	Collection address
currencies	[]string	Currencies bound to this address
callbackUrl	string	Callback URL for collection notifications
createTime	int	Creation time
updateTime	int	First update time
desc	string	Description
ChainShowEn	string	The English name of chain
is_risk	int	mark risk address, 0: normal, 1: risk

Request Example

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/pay/fixedaddress/list?page=0&count=10' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727244774062' \
--header 'X-GatePay-Nonce: 6528576972' \
--header 'X-GatePay-Signature: 6bb0a23cf2f397ab4e602e3dc9d04cad59d265fdfe621bbf978409c6c705f86092c6ac5251c0d349dc93e5fbcf9d6ba2e2beae928d3a01ef72ba9ef8581172e5' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'

Response Example

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "total": 2,
    "list": [
      {
        "channelId": "smart_shop1",
        "chain": "ETH",
        "address": "0xE2b3fA811f04FD5Ac6559007795D6Fc74365126B",
        "currencies": [
          "USDC"
        ],
        "callbackUrl": "https://www.abc.com/callback",
        "createTime": 1727603135221,
        "updateTime": 1727603135221,
        "desc": "",
        "ChainShowEn": "ETH /ERC20",
        "is_risk": 0
      },
      {
        "channelId": "smart_shop",
        "chain": "ETH",
        "address": "0x3FdC81C3f549343a3E0706A382035B7B461C0840",
        "currencies": [
          "DAI",
          "USDT"
        ],
        "callbackUrl": "https://www.abc.com/callback",
        "createTime": 1727603076963,
        "updateTime": 1727603076963,
        "desc": "",
        "ChainShowEn": "ETH /ERC20",
        "is_risk": 1
      }
    ]
  }
}

2.3.9 View Static Collection Address Details

• API Description: View static collection address details

• Data Type: JSON （content-type：application/json）

• Request Method: GET

• Request Headers:

Field Name	Type	Required	Description
X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /merchant/open/institution/v1/pay/fixedaddress/detail

• Validation Method: Merchant signature verification

Interface Description:

Views the details of an already generated and valid static collection address.

Request Parameters:

Field Name	Type	Required	Description
channelId	string	Yes	Merchant channel ID
chain	string	Yes	Network

Response Parameters:

Field Name	Type	Description
channelId	string	The channel ID specified by the merchant when binding the static collection address
chain	string	Network
address	string	Collection address
currencies	[]string	Currencies bound to this address
callbackUrl	string	Callback URL for collection notifications
createTime	int	Creation time
updateTime	int	First update time
desc	string	Description
ChainShowEn	string	The English name of chain
is_risk	int	mark risk address, 0: normal, 1: risk

Request Example

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/pay/fixedaddress/detail?channelId=smart_shop&chain=ETH' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727603139811' \
--header 'X-GatePay-Nonce: 2839411632' \
--header 'X-GatePay-Signature: ca46d4a5b7a516faf6d8d770eeba814004733b9660c35f472b36f4cfa045df2df905b0cdcf3a8212a4c39085ed3843fa721b3dd10cbb931dd32fbf4363d36a52' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'

Response Example

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "channelId": "smart_shop",
    "chain": "ETH",
    "address": "0x5178ff5B10c17282834028E0A79cb18586D44B7C",
    "currencies": [
      "DAI",
      "USDT"
    ],
    "callbackUrl": "https://www.abc.com/callback",
    "createTime": 1727602420837,
    "updateTime": 1727602430742,
    "desc": "",
    "ChainShowEn": "ETH /ERC20",
    "is_risk": 0
  }
}

2.3.10 Delete Static Collection Address

• API Description: Delete static collection address

• Data Type: JSON （content-type：application/json）

• Request Method: DELETE

• Request Headers:

Field Name	Type	Required	Description
X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /merchant/open/institution/v1/pay/fixedaddress/delete

• Validation Method: Merchant signature verification

Interface Description:

Deletes an already generated and valid static collection address.

Request Parameters:

Field Name	Type	Required	Description
channelId	string	Yes	Merchant channel ID
chain	string	Yes	Network

Response Parameters:

Field Name	Type	Description
result	string	ok indicates success; anything else indicates failure

Request Example

curl --location --request DELETE 'https://openplatform.gateapi.io/merchant/open/institution/v1/pay/fixedaddress/delete?channelId=smart_shop&chain=ETH' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727603139811' \
--header 'X-GatePay-Nonce: 2839411632' \
--header 'X-GatePay-Signature: ca46d4a5b7a516faf6d8d770eeba814004733b9660c35f472b36f4cfa045df2df905b0cdcf3a8212a4c39085ed3843fa721b3dd10cbb931dd32fbf4363d36a52' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'

Response Example

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "result": "ok"
  }
}

2.3.11 Query Static Address Order List

• API Description: Query static address order list

• Data Type:JSON （content-type：application/json）

• Request Method:GET

• Request Headers:

Field Name	Type	Required	Description
X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /payment/open/institution/v1/pay/fixedaddress/order/query

• Validation Method: Merchant signature verification

Interface Description:

Request Parameters:

Field Name	Type	Required	Description
channelId	string	Yes	Merchant channel name
chain	string	Yes	Network name
startTime	int	Yes	Order creation time start in milliseconds
endTime	int	Yes	Order creation time end in milliseconds
page	int	Yes	A non-negative integer starting from 0, indicating the page number
count	int	Yes	A positive integer representing the number of entries displayed per page, with a maximum of 100
address	string	No	Collection address
fromAddress	string	No	Payer address
txHash	string	No	Transaction Hash

Response Parameters:

Field Name	Type	Description
total	int	Total amount
list	[]*PaymentDetails	Detail list

PaymentDetails

Field Name	Type	Description
chain	string	Network name
channelId	string	Merchant channel name
currency	string	Currency
address	string	Collection address
amount	string	Income amount
status	string	Order status
txTime	int	Order creation time
fromAddress	string	Payer address
txHash	string	Transaction Hash
transactionId	string	Transaction ID

Request Example

curl --location 'https://openplatform.gateapi.io/payment/open/institution/v1/pay/fixedaddress/order/query?page=0&count=10&chain=ARBEVM&channelId=123456' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727244774062' \
--header 'X-GatePay-Nonce: 6528576972' \
--header 'X-GatePay-Signature: 6bb0a23cf2f397ab4e602e3dc9d04cad59d265fdfe621bbf978409c6c705f86092c6ac5251c0d349dc93e5fbcf9d6ba2e2beae928d3a01ef72ba9ef8581172e5' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'

Response Example

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "total": 1,
    "details": [
      {
        "chain": "ETH",
        "channelId": "123456",
        "currency": "USDT",
        "address": "0x67C30f439D7734f393c2F4a587B198b8F4086Ccb",
        "amount": "0.62345679",
        "status": "PAID",
        "txTime": 1730960078091,
        "fromAddress": "PAzupoupdSYaYoajDcABEUzigBRzewvzN",
        "txHash": "1820949498602496000930038912",
        "transactionId": "343656213785650801"
      }
    ]
  }
}

2.3.12 Create EVM Chain Static Collection Address

• API Description: For the same customer, create a static collection address that can correspond to multiple networks, applicable only to EVM networks.

• Data Type：JSON （content-type：application/json）

• Request Method：POST

• Request Headers:

Field Name	Type	Required	Description
X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /merchant/open/institution/fixedaddress/evm/save

• Validation Method: Merchant signature verification

Interface Description:

Note: Under the same channelId, only one static collection address is allowed per network, and duplicate creation is not permitted.

Request Parameters:

Field Name	Type	Required	Description
channelId	string	Yes	Merchant channel ID， Only letters, numbers, underscores (_), and hyphens (-) are allowed. The maximum length is 50 bytes.
callbackUrl	string	Yes	Callback URL for collection notifications，The length must not exceed 128 bytes.
chianCurrencyInfos	List<ChianCurrencyInfo>	Yes	Network and currency information.

ChianCurrencyInfo Object field description	Type	Required	Description
chain	string	Yes	Network name. Only EVM-compatible networks are supported. When creating a multi-network address, separate network names with commas. Supported EVM networks: ETH, MATIC, ARBEVM, BSC.
currencies	[]string	No	The list of receivable currencies on the network. If not provided, all currencies supported on the network will be used by default.

Response Parameters:

Field Name	Type	Description
channelId	string	Merchant channel ID
address	string	Collection address
callbackUrl	string	Callback URL for this channel
chainInfos	List<ChainInfo>	Includes the network and the currencies supported by the network.

ChainInfo Object field description	Type	Description
chainShowEn	string	The English name of network
currencies	[]string	The list of receivable currencies on the network.

Request Example

curl --location 'https://openplatform.gateapi.io/merchant/open/v1/pay/fixedaddress/evm/save' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1727602580817' \
--header 'X-GatePay-Nonce: 9167310285' \
--header 'X-GatePay-Signature: a23f55ded2e938fd7b6cd436837b21ec8fd413f3dbd496cffae3bedac3a41c7bf684ca46a25484f8b1607d90313ff46aff2d5b75765ef1d97f51bc63f8e0c139' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--data '{
  "channelId": "smart_shop",
  "callbackUrl": "https://www.abc.com/callback",
  "chianCurrencyInfos": [
    {
      "chain": "ETH",
      "currencies": [
      "DAI",
      "USDT"
      ]
    }
  ]
}'

Response Example

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "channelId": "susie",
    "address": "0xE74ac03A2d34A9cEce0A6547b1758C7A8fA10230",
    "callbackUrl": "https://www.abc123.com/callbachttps://www.abc123.com/callbackhttps://www.abc123.com/callbackhttps://www.abc123.com/call",
    "chainInfos": [
      {
        "chainShowEn": "BSC/BEP20",
        "currencies": [
          "USDT"
        ]
      }
    ]
  }
}

2.4 Payout

2.4.1 Create Payout

• Data Type: JSON (content-type: application/json)

• Request Method: POST

• Path: /withdraw/open/institution/v1/pay/create/payouts

• Authentication Method: Signature verification

• Request Body:

  Field Name	Type	Required	Description
  batch_id	string	Yes	Unique ID generated by the merchant, must be unique. Can contain only upper- and lower-case letters, digits, and underscores. Maximum length: 32.
  withdraw_list	array	Yes	List describing the details of each withdrawal sub-order.
  channel_id	string	No	Customer name.

  withdraw_list item fields:

  Field Name	Type	Required	Description
  merchant_withdraw_id	string	Yes	Unique sub-order ID generated by the merchant. Can contain only upper- and lower-case letters, digits, and underscores. Maximum length: 32.
  amount	string	Yes	Single withdrawal amount. Maximum precision is 6 decimal places; if more than 8 decimal digits are provided, the extra digits will be truncated.
  currency	string	Yes	Withdrawal currency.
  chain	string	Yes	Network chain.
  address	string	Yes	Withdrawal address.
  memo	string	Yes	Transfer remark / memo. For transfers on the TON network this field is required; providing it when not needed may cause failures. Maximum length: 128.
  fee_type	int	Yes	Fee charging method for the withdrawal: If internal deduction is selected, the fee is deducted from the withdrawal amount, and the credited amount equals withdrawal amount minus fee. If external charging is selected, the fee is deducted from the account balance, and the credited amount equals the withdrawal amount. If not provided for legacy orders, the default is internal deduction. Enum values: 0 - internal deduction 1 - external charging

Request Example:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/v1/pay/create/payouts' \
--header 'X-GatePay-Certificate-SN: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-raw '{
    "batch_id": "M57143269150",
    "withdraw_list": [
        {
            "merchant_withdraw_id": "e1619185671595",
            "currency": "USDT",
            "amount": "0.01",
            "chain": "ETH",
            "address": "THISISTESTADDRESSFORGATEPAY1",
            "memo": "",
            "fee_type": 0
        }
    ]
}'

Response Example:

{
    "code": "000000",
    "data": {
        "batch_id": "M57143269148"
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

Response Body:

Field Name	Type	Description
batch_id	string	Unique ID generated by merchant.

2.4.2 Payout Details

• Data Type: JSON (content-type: application/json)

• Request Method: POST

• Path: /withdraw/open/institution/v1/pay/payouts/detail

• Authentication Method: Signature verification

• Request Body:

Field Name	Type	Required	Description
batch_id	string	Yes	Unique ID generated by the merchant via /v1/pay/withdraw.
detail_status	string	Yes	Query status for sub-orders: ALL - all sub-orders INIT - newly created sub-orders PENDING - pending sub-orders PROCESSING - submitted withdrawal request, pending confirmation sub-orders CHECK - sub-orders under review FAIL - failed sub-orders DONE - successfully completed withdrawal sub-orders

• Response Body:

Parent Order Fields

Field Name	Type	Description
batch_id	string	Batch ID.
merchant_id	int64	Merchant ID.
client_id	string	Client ID of the merchant that created the order.
status	string	Status of the parent order.
create_time	int64	Parent order creation time (ms).
withdraw_list	array	Sub-order information.
channel_id	string	Customer name.

Payout parent order status enum:

Status	Description
INIT	Newly created order.
PROCESSING	Payout order is being processed.
PARTIAL	Partially successful.
FAIL	All sub-orders failed.
SUCCESS	All sub-orders succeeded.

Sub-order (withdraw_list) Fields

Field Name	Type	Description
id	int64	Record ID.
batch_id	string	Merchant batch withdrawal ID.
merchant_id	int64	Merchant ID.
channel_id	string	Customer name.
suborder_id	string	Sub-order ID generated by GatePay.
withdraw_id	string	Withdrawal transaction ID. Use this ID to query the withdrawal order.
chain	string	gate_chain network name.
address	string	Withdrawal address.
currency	string	Currency.
amount	decimal.Decimal	Initiated withdrawal amount.
fee	decimal.Decimal	Fee amount.
tx_id	string	Transaction hash.
timestamp	int64	Operation time on the deposit/withdraw side (ms).
memo	string	Transfer memo / remarks.
status	string	Status.
merchant_withdraw_id	string	Merchant withdrawal ID.
err_msg	string	Reason for withdrawal failure.
create_time	int64	Creation time (ms).
update_time	int64	Update time (ms).
fee_type	int8	0 - amount is the debited amount; 1 - amount is the credited amount.
batch_withdraw_id	string	Deprecated.
desc	string	Not a DB column; customer/channel remark.
reconciliation_status	int8	Withdrawal reconciliation status: 0 - not reconciled, 1 - reconciliation in progress, 2 - mismatch, 3 - reconciliation matched.
is_placed	int	0 - not placed; 1 - order placed.
finish_time	int64	Order completion time (ms).
sub_amount	decimal.Decimal	Total debited amount (fee amount + credited amount).
done_amount	decimal.Decimal	Credited amount.

Payout sub-order status enum:

Status	Description
INT	Created state.
PENDING	Created, order pending processing.
PROCESSING	Order is being processed.
CHECK	Under review.
FAIL	Wallet withdrawal failed.
DONE	Withdrawal succeeded.

Request Example:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/v1/pay/payouts/detail' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-raw '{
    "batch_id":"M57143269150"
}'

Response Example:

{
    "code": "000000",
    "data": {
        "batch_id": "M57143269148",
        "merchant_id": 2124538349,
        "client_id": "mZ96D37oKk-HrWJc",
        "status": "PROCESSING",
        "create_time": 1764048644523,
        "withdraw_list": [
            {
                "id": 634708,
                "batch_id": "M57143269148",
                "merchant_id": 2124538349,
                "suborder_id": "35803766522511370",
                "withdraw_id": "",
                "chain": "ETH",
                "address": "THISISTESTADDRESSFORGATEPAY1",
                "currency": "USDT",
                "amount": 0.01000000,
                "fee": "0",
                "tx_id": "",
                "timestamp": 1764048644540,
                "memo": "",
                "create_time": 1764048644540,
                "update_time": 1764048644891,
                "status": "PENDING",
                "err_msg": "",
                "merchant_withdraw_id": "e1619185671593",
                "desc": "",
                "channel_id": null,
                "finish_time": 0,
                "sub_amount": 0.00000000,
                "done_amount": "0"
            }
        ],
        "channel_id": ""
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

If the batch_id does not exist, an empty result is returned:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "batch_id": "237394559478075358",
        "merchant_id": 0,
        "client_id": "",
        "status": "",
        "create_time": 0,
        "withdraw_list": []
    }
}

2.5 Transfer

2.5.1 Initiate Transfer - Institution to User

• Data Type: JSON (content-type: application/json)

• Request Method: POST

• Path: /transfer/open/institution/v1/pay/transfer

• Authentication Method: Signature verification

• Request Body:

Field Name	Type	Required	Description
merchantBatchNo	string	Yes	Unique ID generated by the merchant.
accountId	string	Yes	Recipient account ID.
currency	string	Yes	Transfer currency.
amount	string	Yes	Transfer amount.

• Response Body:

Field Name	Type	Description
merchantBatchNo	string	Batch ID, identical to the input merchantBatchNo.

Request Example:

curl --location --request POST 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/transfer' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'X-GatePay-ClientId;' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-raw '{
  "merchantBatchNo": "1234565454511231",
  "currency": "USDT",
  "amount": "1",
  "accountId": "1979044675"
}'

Response Example:

{
    "code": "000000",
    "data": {
        "merchantBatchNo": "1234565454511231"
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

2.5.2 Transfer Details - Institution to User

• Data Type: JSON (content-type: application/json)

• Request Method: GET

• Path: /transfer/open/institution/v1/pay/transfer/detail

• Authentication Method: Signature verification

• Request Body:

Field Name	Type	Required	Description
merchantBatchNo	string	Yes	Unique ID generated by the merchant.

• Response Body:

Field Name	Type	Description
merchantBatchNo	string	Batch ID, identical to the input merchantBatchNo.
status	string	Order status: ERROR - failed EXPIRED - expired PAID - succeeded PENDING - pending PROCESSING - processing CANCEL - canceled CANCELLED - closed.
toAccountId	string	Receiving account.
fromAccountId	string	Paying account.
createTime	long	Order time in milliseconds.
currency	string	Currency.

Request Example:

curl --location --request GET 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/transfer/detail?merchantBatchNo=12345654545' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp;' \
--header 'x-GatePay-Nonce;' \
--header 'x-GatePay-Signature;' \
--header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'X-GatePay-MerchantId: 10002' \
--header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' \
--header 'X-Gate-User-Id: 10002' \
--header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' \
--header 'Content-Type: application/json' \
--data-binary '@<body data here>'

Response Example:

{
    "code": "000000",
    "data": {
        "merchantBatchNo": "12345654545",
        "status": "PENDING",
        "fromAccountId": "2124267192",
        "toAccountId": "1979044675",
        "currency": "USDT",
        "amount": "1",
        "createTime": 1763455435851
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

2.6 Direct Debit (User to Institution)

2.6.1 Initiate Direct Debit – User Transfers to Institution

• Data type: JSON (content-type: application/json)

• Request method: POST

• Path: /transfer/open/institution/v1/pay/charge

• Authentication: Signature verification

• Request body:

Field name	Type	Required	Description
merchantBatchNo	string	Yes	Unique ID generated by the merchant
accountId	string	Yes	Recipient account ID
currency	string	Yes	Transfer currency
amount	string	Yes	Transfer amount

• Response body:

Field name	Type	Description
merchantBatchNo	string	Batch ID, identical to the input merchantBatchNo value

Request example:

curl --location --request POST 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/charge' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp;' --header 'x-GatePay-Nonce;' --header 'x-GatePay-Signature;' --header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' --header 'X-GatePay-On-Behalf-Of: 2124538349' --header 'X-GatePay-ClientId;' --header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' --header 'X-Gate-User-Id: 10002' --header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' --header 'Content-Type: application/json' --data-raw '{
  "merchantBatchNo": "1234565454511231",
  "currency": "USDT",
  "amount": "1",
  "accountId": "1979044675"
}'

Response example:

{
  "code": "000000",
  "data": {
    "merchantBatchNo": "1234565454511231"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.6.2 Direct Debit – User-to-Institution Transfer Details

• Data type: JSON (content-type: application/json)

• Request method: GET

• Path: /transfer/open/institution/v1/pay/charges/detail

• Authentication: Signature verification

• Request parameters:

Field name	Type	Required	Description
merchantBatchNo	string	Yes	Unique ID generated by the merchant

• Response body:

Field name	Type	Description
merchantBatchNo	string	Batch ID, identical to the input merchantBatchNo value
status	string	Status values: ERROR: failed EXPIRED: expired PAID: successful PENDING: pending PROCESSING: processing CANCEL: cancelled CANCELLED: closed
toAccountId	string	Receiving account
fromAccountId	string	Payer account
createTime	long	Order creation time in milliseconds
currency	string	Currency

Request example:

curl --location --request GET 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/transfer/detail?merchantBatchNo=12345654545' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp;' --header 'x-GatePay-Nonce;' --header 'x-GatePay-Signature;' --header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' --header 'X-GatePay-On-Behalf-Of: 2124538349' --header 'X-GatePay-MerchantId: 10002' --header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' --header 'X-Gate-User-Id: 10002' --header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' --header 'Content-Type: application/json' --data-binary '@<body data here>'

Response example:

{
  "code": "000000",
  "data": {
    "merchantBatchNo": "12345654545",
    "status": "PENDING",
    "fromAccountId": "2124267192",
    "toAccountId": "1979044675",
    "currency": "USDT",
    "amount": "1",
    "createTime": 1763455435851
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.7 Refund

2.7.1 Create Refund API

• Data type: JSON (content-type: application/json)

• Request method: POST

• Path: /payment/open/institution/v2/standard/order/refund

• Authentication: Signature verification

• Request body:

Field name	Type	Required	Description
refundRequestId	string	Yes	Merchant refund ID. Unique ID generated by the merchant, no longer than 32 bytes
prepayId	string	Yes	Order ID. The order must be in paid status before a refund can be initiated
refundAmount	string	Yes	Refund amount
refundReason	string	Yes	Refund reason
refundStyle	int64	No	Refund method: 1 = original route, 2 = designated route
refundPayChannel	int64	No	Refund payment method: 1 = Gate, 2 = Web3
refundToGateUid	string	No	Refunded Gate user ID; required if refund method is Gate
refundChain	string	No	Refund network; required if refund method is Web3
refundBearType	string	No	Refund fee bearer type: 1 = merchant bears, 2 = user bears
memo	string	No	Refund remark
refundAmountTypeFull	string	No	Refund amount type: 1 = full refund, 2 = partial refund
needNotify	boolean	No	Whether notification is required
refundLimit	boolean	No	Whether the number of refunds is limited
refundCurrency	string	No	Refund currency
refundFundStatementId	int64	No	Statement ID of the transaction from which the refund is initiated
refundSource	int64	No	Refund source: 0 = order, 1 = statement

• Response parameters:

Field name	Type	Description
refundRequestId	string	Merchant refund request ID
prepayId	string	Order ID
refundGateId	string	GatePay refund order ID
orderAmount	string	Order amount
refundAmount	string	Refund amount
errMsg	string	Error message
orderCurrency	string	Order currency
payCurrency	string	Refund currency
payAmount	string	Merchant payment amount

Request example:

curl --location --request POST 'https://openplatform.gateapi.io/payment/open/institution/v2/standard/order/refund' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp;' --header 'x-GatePay-Nonce;' --header 'x-GatePay-Signature;' --header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' --header 'X-GatePay-On-Behalf-Of: 2124538349' --header 'GatePay-client-Type: IOS' --header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' --header 'X-Gate-User-Id: 10002' --header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' --header 'Content-Type: application/json' --data-raw '{
    "prepayId": "1991810932510167040",
    "refundRequestId": "lux202511x=093726",
    "refundStyle": 2,
    "refundToGateUid":2124538349,
    "refundAmount": "0.018",
    "currency": "USDT",
    "refundPayChannel": 1,
    "refundReason":"test",
    "refundBearType":1
}'

Response example:

{
  "code": "000000",
  "data": {
    "refundRequestId": "lux202511x=093725",
    "refundGateId": "35803047115358215",
    "prepayId": "1991810932510167040",
    "orderAmount": "1.1",
    "refundAmount": "0.018",
    "errMsg": "",
    "orderCurrency": "USDT",
    "payCurrency": "USDT",
    "payAmount": "0.018"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.7.2 Query Refund Details API

• Data type: JSON (content-type: application/json)

• Request method: GET

• Path: /payment/open/institution/v2/pay/refund/details

• Authentication: Merchant signature verification

• Request parameters:

Field name	Type	Required	Description
refundRequestId	string	Yes	Refund order ID generated by the merchant. Must be unique and no longer than 32 characters

• Response parameters:

Field name	Type	Description
refundRequestId	string	Merchant refund order ID
gateRefundId	string	Refund order ID generated by GatePay
refundId	string	Merchant refund order ID
orderId	string	GatePay payment order ID
merchantTradeNo	string	Merchant order ID
createTime	int64	Refund order creation time
transactTime	int64	Payment time
transactionId	string	Payment transaction order ID
txHash	string	Transaction hash; present only for Web3 refunds
orderAmount	string	Order amount
orderCurrency	string	Order currency
requestAmount	string	Requested refund amount
requestCurrency	string	Requested refund currency
amount	string	Refunded amount
currency	string	Refund currency
status	string	Refund status
remark	string	Refund order remark
refund_style	string	Refund method: 1 = original route, 2 = designated route
refund_pay_channel	string	Refund payment method: 1 = gate, 2 = web3
refund_address	string	Refund address
refund_chain	string	Refund network
refund_bear_type	string	Refund fee bearer type: 1 = merchant bears, 2 = user bears
refund_amount_type	string	Refund amount type: 1 = full refund, 2 = partial refund
refund_account_type	string	Refund debit account type: 1 = payment account, 2 = spot account
refund_gas_amount	string	Refund gas fee; only present for Web3 refunds
refund_fail_reason	string	Refund failure reason
refund_to_gate_uid	string	Gate user UID receiving the refund
channelId	string	Customer channel name
nickName	string	User nickname
payerId	string	User UID
fromAddress	string	Payer address
payChannel	string	Payment method: Web3 payment Gate payment
billType	string	Bill type
goodsName	string	Product name
totalRequestAmount	string	Order-level requested refund amount
totalRequestCurrency	string	Order-level requested refund currency
totalReceiveAmount	string	Order-level actual received order amount
totalReceiveCurrency	string	Order-level actual received order currency
refundDetails	[] RefundDetailItem	Refund order details list

RefundDetailItem structure:

Field name	Type	Description
transactionId	string	Payment transaction order ID
transactTime	int64	Payment time
payChannel	string	Payment channel
status	string	Payment status
amount	string	Refund amount
currency	string	Refund currency
chain	string	Network information
address	ChainItem	Merchant receiving address
hash	string	Transaction hash
remark	string	Remark
billType	string	Bill type

Refund order status enumeration values:

Value	Description
PENDING	Order pending
PROCESS	Order processing
CHECK	Order under review
SUCCESS	Refund successful
FAIL	Refund failed

Request example:

curl --location --request GET 'https://openplatform.gateapi.io/payment/open/institution/v2/pay/refund/details?refundRequestId=lux202511x=093726' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp;' --header 'x-GatePay-Nonce;' --header 'x-GatePay-Signature;' --header 'x-gate-auth-apptoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' --header 'X-GatePay-On-Behalf-Of: 2124538349' --header 'GatePay-client-Type: IOS' --header 'Cookie: lang=cn; login_notice_check=%2F; exchange_rate_switch=1; defaultBuyCryptoFiat=USD; curr_fiat=USD; _fbp=fb.3.1758860370923.560494710568093824; _dx_uzZo5y=bbda21e11c7b32719303ae2ce8a0409d85d275d8d6cf0b6bcb5cce2e8d050b3a90249b75; auth_last_login_tab=1; auth_site_id=0; b_notify=1; _ga_SNPLSCMNGD=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga_CF71BLYRCR=GS2.1.s1760668889$o4$g1$t1760669000$j60$l0$h0; _ga=GA1.4.1870205018.1758860371; curr_symbol=%24; uid=10002; nickname=future_10002; is_on=1; pver=8a65fd779dc95e2e30ae2a281ce38ad8; pver_ws=6fd9f1c5f183a1a859e25dfa7c8d80f6; csrftoken=47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257; token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjM5NjM0MTIsImlwIjoiQ2Vsd2o0VXo5QWZpVUxVOFZYRkFGNlg2ZDE5bkNtd21acGswNmI3dVlUQzRCNkwyRlFiMHc2TT0iLCJpcFJlc3RyaWN0IjoiM244T3RZbE9aTFFpT0hNMHVYeUpEZFlFZEgzVzcvcHZaZFNocm9BPSIsImRldmljZVR5cGUiOiJaTkdaY0hwNHo0V0RuUFR4ejRZS1NCUGJ3Q2NmVWV2N2dSY3ZTbmc9IiwiZGV2aWNlSWQiOiI3TzVSbllIWS9hMkk5eGovZUZmZGJQS1VtK0R3WWxQblprMmw3UT09IiwidWlkIjoiWlNFbXZjSFM4dkdOWktsL2xaNUpkRlVOU0FZa1Fza0w0b2F4SGdpS24zeTYifQ.Gn3jLMWl_cWDeK0Ryc4DvSMZPbna5DgqDj0xEiHntkM; token_type=Bearer; is_login=1; sub_website_id=0; _gid=GA1.4.1320370387.1764149872; uid_merchantId=10002; finger_print=6926ca71EpYjYdpkYUHCVGyOnLqnuoys03KnDJN1; _ga_JNHPQJS9Q4=GS2.4.s1764220485$o48$g0$t1764220485$j60$l0$h0; lasturl=%2Fpay-merchant%2Fdeveloper%2Fapp-configuration' --header 'X-Gate-User-Id: 10002' --header 'csrftoken: 47524b52484b6e79794d6a3072765a493356574563787469316d43796c6a644d4a4473544663545263643759474e314d79565431502b6279524b4a4731797257' --header 'Content-Type: application/json' --data-raw ''

Response example:

{
  "code": "000000",
  "data": {
    "refundRequestId": "lux202511x=093725",
    "gateRefundId": "35803047115358215",
    "refundId": "lux202511x=093725",
    "orderId": "1991810932510167040",
    "merchantTradeNo": "lux202511x=0937",
    "createTime": 1764047402963,
    "transactTime": 1764047403042,
    "transactionId": "35803047115358215",
    "txHash": "",
    "orderAmount": "1.1",
    "orderCurrency": "USDT",
    "requestAmount": "0.018",
    "requestCurrency": "USDT",
    "amount": "0.018",
    "currency": "USDT",
    "status": "SUCCESS",
    "remark": "test",
    "channelId": "",
    "nickName": null,
    "payerId": 2124538349,
    "fromAddress": "",
    "refundDetails": null,
    "payChannel": "",
    "billType": 2,
    "goodsName": "Goods",
    "totalRequestAmount": "0.126",
    "totalRequestCurrency": "USDT",
    "totalReceiveAmount": "1.1",
    "totalReceiveCurrency": "USDT",
    "refund_style": 2,
    "refund_pay_channel": 1,
    "refund_address": "",
    "refund_chain": "",
    "refund_bear_type": 1,
    "refund_amount_type": 0,
    "refund_account_type": 0,
    "refund_gas_amount": "0",
    "refund_fail_reason": "",
    "refund_to_gate_uid": 2124538349
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.8 Instant Conversion

2.8.1 Query Available Currencies for Instant Conversion

• Data type: JSON (content-type: application/json)

• HTTP method: GET

• Path: /transfer/open/institution/v1/pay/convert/currency

• Authentication: Signature verification

• Request parameters (Query String):

  Field Name	Type	Required	Description
  side	string	No	Trading side, valid values: "buy" or "sell"

• Response body

  Field Name	Type	Required	Description
  currency	string	Yes	Currency

• CURL Request

curl --location 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/convert/currency?side=sell' --header 'X-GatePay-Certificate-ClientId: SkZlbKOqPoMwnxhl' --header 'X-GatePay-Timestamp: 1740018226125' --header 'x-GatePay-Nonce: 5241889066' --header 'x-GatePay-Signature: a428f2afc6103b515d4a774ffe8dda9f10bbe1a9815d4c10598f281e5db014e93c7ae42b6cff0c77166e136e5951261e6bcfc4672582483b814bf604ade50bb4' --header 'Content-Type: application/json'

• Response

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "currency": [
            "USDT",
            "GT",
            "HOOK",
            "ETH",
            "DOT",
            "BTC",
            "DAL",
            "LTC",
            "COS",
            "POL",
            "SOL",
            "DOGE",
            "ALGO",
            "STPT",
            "BCH",
            "SHIB"
        ]
    }
}

2.10.2 Query Available Currency Pairs

• Data type: JSON (content-type: application/json)

• HTTP method: GET

• Path: /transfer/open/institution/v1/pay/convert/pair

• Authentication: Signature verification

• Request parameters (Query String):

  Field Name	Type	Required	Description
  side	string	No	Trading side, valid values: "buy" or "sell"
  currency	string	Yes	Currency

• Response body

  Field Name	Type	Required	Description
  pair	string	Yes	Currency pair
  sellCurrency	string	Yes	Sell currency
  buyCurrency	string	Yes	Buy currency
  sellCurrencyMax	string	Yes	Maximum amount of sell currency
  buyCurrencyMax	string	Yes	Maximum amount of buy currency
  buyCurrencyMin	string	Yes	Minimum amount of buy currency
  sellCurrencyMin	string	Yes	Minimum amount of sell currency

• CURL Request

curl --location 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/convert/pair?currency=GT&side=buy' --header 'Content-Type: application/json' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp: 1740018611625' --header 'x-GatePay-Nonce: 3347302609' --header 'x-GatePay-Signature: 7209e852c0fca24a9430d097f93331b7d2bac82b2710763a73af67340b67c2d8fef524051d30a3ff42258a93a200b08fdd5849ec2d2fa0f7c7ba9ed52ce38010'

• Response

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": [
        {
            "pair": "BTC_USDT",
            "sellCurrency": "BTC",
            "sellCurrencyMax": "31",
            "sellCurrencyMin": "0.0002",
            "buyCurrency": "USDT",
            "buyCurrencyMax": "1980000",
            "buyCurrencyMin": "12"
        },
        {
            "pair": "BNB_USDT",
            "sellCurrency": "BNB",
            "sellCurrencyMax": "410",
            "sellCurrencyMin": "0.1",
            "buyCurrency": "USDT",
            "buyCurrencyMax": "100000",
            "buyCurrencyMin": "10"
        } 
    ]
}

2.10.3 Preview Quote

• Data type: JSON (content-type: application/json)

• HTTP method: POST

• Path: /transfer/open/institution/v1/pay/convert/preview

• Authentication: Signature verification

• Request body:

  Field Name	Type	Required	Description
  buyCurrency	string	Yes	Buy currency
  buyAmount	string	No	Buy amount, mutually exclusive with sellAmount
  sellCurrency	string	Yes	Sell currency
  sellAmount	string	No	Sell amount, mutually exclusive with buyAmount

• Response body

  Field Name	Type	Required	Description
  sellCurrency	string	Yes	Sell currency
  buyCurrency	string	Yes	Buy currency
  sellAmount	string	Yes	Sell amount
  buyAmount	string	Yes	Buy amount
  rate	string	Yes	Price
  quoteId	string	Yes	Quote ID

• CURL Request

curl --location 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/convert/preview' --header 'Content-Type: application/json' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp: 1740019013818' --header 'x-GatePay-Nonce: 9722139164' --header 'x-GatePay-Signature: 8504fe097f7297f8952c76e628ce59dbc93d1df64c95f26c73140ef365d4aa1471826ada0534315461682ec35c131d7e133c51d2ab0822fe7366650a111887ba' --data '{
    "buyCurrency":"USDT",
    "buyAmount":"1",
    "sellCurrency":"GT"

}'

• Response

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "sellCurrency": "GT",
        "buyCurrency": "USDT",
        "buyAmount": "1",
        "sellAmount": "0.04466796",
        "rate": "22.38741462",
        "quoteId": "PAY-16991c65"
    }
}

2.10.4 Initiate Instant Conversion

• Data type: JSON (content-type: application/json)

• HTTP method: POST

• Path: /transfer/open/institution/v1/pay/convert

• Authentication: Signature verification

• Request body:

  Field Name	Type	Required	Description
  clientReqId	string	Yes	Client request ID (randomly generated by the client to ensure idempotency)
  quoteId	string	Yes	Quote ID (must match the value returned by the preview API)
  buyAmount	string	Yes	Buy amount (must match the value returned by the preview API)
  buyCurrency	string	Yes	Buy currency (must match the value returned by the preview API)
  sellAmount	string	Yes	Sell amount (must match the value returned by the preview API)
  sellCurrency	string	Yes	Sell currency (must match the value returned by the preview API)

• Response body

  Field Name	Type	Required	Description
  order_id	string	Yes	Order ID
  userId	string	Yes	User ID
  sellCurrency	string	Yes	Sell currency
  buyCurrency	string	Yes	Buy currency
  sellAmount	string	Yes	Sell amount
  buyAmount	string	Yes	Buy amount
  status	string	Yes	Status: 1 - created, 3 - succeeded, 6 - failed
  rate	string	Yes	Price
  quoteId	string	Yes	Quote ID
  createTime	string	Yes	Creation time

• CURL Request

curl --location 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/convert' --header 'Content-Type: application/json' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp: 1740019013818' --header 'x-GatePay-Nonce: 9722139164' --header 'x-GatePay-Signature: 8504fe097f7297f8952c76e628ce59dbc93d1df64c95f26c73140ef365d4aa1471826ada0534315461682ec35c131d7e133c51d2ab0822fe7366650a111887ba' --data '{
    "clientReqId":"181147",
    "sellCurrency": "GT",
    "buyCurrency": "USDT",
    "buyAmount": "1",
    "sellAmount": "0.04464002",
    "price": "22.40142565",
    "quoteId": "PAY-2a5743d8"
}'

• Response

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "order_id": "327196066546229248",
        "userId": 10002,
        "sellCurrency": "GT",
        "buyCurrency": "USDT",
        "sellAmount": "0.04464002",
        "buyAmount": "1",
        "status": 1,
        "rate": 22.40142365527614,
        "quoteId": "PAY-2a5743d8",
        "createTime": 1739971221273
    }
}

2.10.5 Query Instant Conversion Order

• Data type: JSON (content-type: application/json)

• HTTP method: GET

• Path: /transfer/open/institution/v1/pay/convert/order

• Authentication: Signature verification

• Request parameters (Query String):

  Field Name	Type	Required	Description
  OrderID	string	Yes	Order ID

• Response body

  Field Name	Type	Required	Description
  order_id	string	Yes	Order ID
  userId	string	Yes	User ID
  sellCurrency	string	Yes	Sell currency
  buyCurrency	string	Yes	Buy currency
  sellAmount	string	Yes	Sell amount
  buyAmount	string	Yes	Buy amount
  status	string	Yes	Status: 1 - created, 3 - succeeded, 6 - failed
  rate	string	Yes	Price
  quoteId	string	Yes	Quote ID
  createTime	string	Yes	Creation time

• CURL Request

curl --location --request GET 'https://openplatform.gateapi.io/transfer/open/institution/v1/pay/convert/order?orderId=326850433152987136' --header 'Content-Type: application/json' --header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' --header 'X-GatePay-Timestamp: 1740021137456' --header 'x-GatePay-Nonce: 3735215968' --header 'x-GatePay-Signature: 77516a1010d9c8d1f0b8e1d72810b62195ca01f8c1000558a7b1b9de4d79c13200d17036d6e4e555bc2bc4a5ca114b44b616dca03b5f9b72687eb34ebee1515d' --data '{
    "buyCurrency":"BTC",
    "buyAmount":"1",
    "sellCurrency":"ETH",
    "sellAmount":"0"
}'

• Response

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "order_id": "326850433152987136",
        "userId": 10002,
        "sellCurrency": "USDT",
        "buyCurrency": "GT",
        "sellAmount": "1",
        "buyAmount": "0.04369692",
        "status": 6,
        "rate": 22.884908135401762,
        "quoteId": "PAY-52f30798",
        "createTime": 1739888815851
    }
}

2.9 Otc Withdraw

2.9.1 Get Quote

• API Description: Before creating a fiat withdrawal order, merchants must first request a quote to obtain an executable price and its validity period. During the validity period, the quote token locks the exchange rate, amount, and currency. Once a quote is successfully obtained, the merchant must execute the quote using the quote token within the validity period to create an order.

• Data Type: JSON (content-type: application/json)

• Request Method: POST

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /withdraw/open/institution/otc/api/v1/quote

• Authentication Method: Signature Verification

• Request Body:

Field Name	Type	Required	Description
cryptoCurrency	string	Yes	Cryptocurrency. Currently supported: USDT only
fiatCurrency	string	Yes	Fiat currency. Currently supported: USD only
cryptoAmount	string	No	Cryptocurrency amount. Required when side is CRYPTO
fiatAmount	string	No	Fiat amount. Required when side is FIAT
side	string	Yes	Quote Direction: CRYPTO: Quote based on cryptocurrency amount (cryptoAmount is required) FIAT: Quote based on fiat amount (fiatAmount is required)
promotionCode	string	No	Promotion code
type	string	Yes	BUY: Deposit SELL: Withdrawal Currently supported: SELL only

• Response Body:

Field Name	Type	Description
cryptoCurrency	string	Cryptocurrency
fiatCurrency	string	Fiat currency
cryptoAmount	string	Cryptocurrency amount
fiatAmount	string	Fiat amount
fiatRate	string	Fiat exchange rate (fiat/crypto)
cryptoRate	string	Crypto exchange rate (crypto/fiat)
validPeriod	integer	Quote validity period, in seconds
quoteToken	string	Quote token, used to place an order

CURL Request:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/v1/quote' \\
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \\
--header 'X-GatePay-Timestamp: 1769588949' \\
--header 'x-GatePay-Nonce: 2730095202' \\
--header 'x-GatePay-Signature: 7f780aa07e120dda16f0b0139e86a32ebe9833f10b3bf75fafc55dea46658e14a3f18078fa45ecfd9b81b4edf2c0bc91d1d9dc9ca4de5eed3189437f8e31fd69' \\
--header 'Content-Type: application/json' \\
--data-raw '{
"cryptoCurrency": "USDT",
"fiatCurrency": "USD",
"cryptoAmount": "1000",
"side": "CRYPTO",
"type": "SELL"
}'

Response:

{
  "code": "",
  "data": {
    "cryptoCurrency": "USDT",
    "fiatCurrency": "USD",
    "cryptoAmount": "10000",
    "fiatAmount": "9898.72",
    "fiatRate": "0.989872",
    "cryptoRate": "1.01023613",
    "validPeriod": 300,
    "quoteToken": "adhk543"
  },
  "status": "",
  "label": "",
  "errorMessage": ""
}

2.9.2 Create Order

• API Description: After obtaining a quote, the merchant must execute the quote within its validity period to create a fiat withdrawal order.

• Data Type: JSON (content-type: application/json)

• Request Method: POST

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /withdraw/open/institution/otc/api/order/create

• Authentication Method: Signature Verification

• Request Body:

Field Name	Type	Required	Description
quoteToken	string	Yes	Quote token
bankAccountId	string	Yes	Bank account ID
cryptoCurrency	string	Yes	Cryptocurrency
fiatCurrency	string	Yes	Fiat currency
cryptoAmount	string	Yes	Cryptocurrency amount
fiatAmount	string	Yes	Fiat amount
type	string	Yes	BUY: Deposit SELL: Withdrawal Currently supported: SELL only
clientOrderId	string	Yes	Merchant Order Number; Create order failed, please change the order number

• Response Body:

Field Name	Type	Description
orderId	string	Order ID
status	string	Order status
createTime	integer	Creation Time
clientOrderId	string	Merchant Order Number

CURL Request:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/order/create' \\
--header 'Content-Type: application/json' \\
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \\
--header 'X-GatePay-Timestamp: 1769669668127' \\
--header 'x-GatePay-Nonce: 7508857261' \\
--header 'x-GatePay-Signature: 9636bd4c3edac24af5ea2b410c38aa0bafc7e73d6333158205a3f3652cfd97e2a94e38a259a057bee565889b1c686a22b03943a196c19d1eaa43ecb5a045cec1' \\
--data-raw '{
"cryptoCurrency": "USDT",
"fiatCurrency": "USD",
"cryptoAmount": "10000",
"fiatAmount": "9800",
"type": "SELL",
"quoteToken": "qdfh34543",
"bankAccountId": "2897434"
}'

Response:

{
  "code": "000000",
  "data": {
    "orderId": "2016768770965639168",
    "status": "PROCESSING",
    "createTime": 1769670119407
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.3 Query Order Details

• API Description: After a quote is executed and an order is successfully created, merchants can query the order status and related details using the returned order ID.

• Data Type: JSON (content-type: application/json)

• Request Method: GET

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /withdraw/open/institution/otc/api/order/detail

• Authentication Method: Signature Verification

• Request Parameters:

Field Name	Type	Required	Description
orderId	string	No	Order ID.Required when clientOrderId is null
clientOrderId	string	No	Merchant Order Number.Required when orderId is null

• Response Body:

Field Name	Type	Description
orderId	string	Order ID
status	string	Order Status: PROCESSING: Processing FAIL: Failure DONE: Success DISPATCHED: Dispatched
cryptoCurrency	string	Cryptocurrency
fiatCurrency	string	Fiat currency
type	string	BUY: Deposit SELL: Withdrawal
cryptoAmount	string	Cryptocurrency amount
fiatAmount	string	Fiat amount
fiatRate	string	Fiat exchange rate (fiat/crypto)
bankAccountId	string	Bank Account ID
createTime	integer	Creation Time
updateTime	integer	Last update time
clientOrderId	string	Merchant Order Number
errMsg	string	Failure reason
tradeFee	string	Fee (in same currency as fiatCurrency)
finalFiatAmount	string	Net amount (in same currency as fiatCurrency)

CURL Request:

curl --location --request GET 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/order/detail?orderId=35599620284481595' \\
--header 'Content-Type: application/json' \\
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \\
--header 'X-GatePay-Timestamp: 1769670845426' \\
--header 'x-GatePay-Nonce: 9099836565' \\
--header 'x-GatePay-Signature: 3eef45b012cf9710eb06587775f5fc2807b7445fb0fdd3c830cf453ee07b34824c0b4bf187a1ad783f886c592b04da7b0ab5d8bf47b8741c82bd408db7b811b4'

Response:

{
  "code": "000000",
  "data": {
    "cryptoCurrency": "USDT",
    "fiatCurrency": "USD",
    "cryptoAmount": "100000",
    "fiatAmount": "99810.08",
    "orderId": "35599620284481595",
    "status": "DONE",
    "createTime": 1761205415973,
    "updateTime": 1761205416189,
    "bankAccountId": "123141284812832183",
    "type": "SELL",
    "fiatRate": "0.9981"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.4 Query Order List

• API Description: After executing quotes and creating orders, merchants can query order status and related details in batches using the returned order ID.

• Data Type: JSON (content-type: application/json)

• Request Method: POST

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /withdraw/open/institution/otc/api/order/list

• Authentication Method: Signature Verification

• Request Body:

Field Name	Type	Required	Description
status	string	No	Order Status: PROCESSING: Processing FAIL: Failure DONE: Success DISPATCHED: Dispatched
type	string	No	BUY: Deposit SELL: Withdrawal
cryptoCurrency	string	No	Cryptocurrency
fiatCurrency	string	No	Fiat currency
startTime	string	No	Start time (creation time)
endTime	string	No	End time (creation time)
page	integer	No	Page number, default 1
pageSize	integer	No	Page size, default 10, maximum 500
clientOrderId	string	No	Merchant Order Number

• Response Body:

Field Name	Type	Description
data	array	Order list
data[].order_id	string	Order ID
data[].status	string	Order Status: PROCESSING: Processing FAIL: Failure DONE: Success DISPATCHED: Dispatched
data[].cryptoCurrency	string	Cryptocurrency
data[].fiatCurrency	string	Fiat currency
data[].bankAccountId	string	Bank Account ID
data[].cryptoAmount	string	Cryptocurrency amount
data[].fiatAmount	string	Fiat amount
data[].fiatRate	string	Fiat exchange rate (Fiat/Crypto)
data[].createTime	integer	Creation Time
data[].updateTime	integer	Last update time
data[].type	string	BUY: Deposit SELL: Withdrawal
data[].clientOrderId	string	Merchant Order Number
data[].errMsg	string	Failure reason
data[].tradeFee	string	Fee (in same currency as fiatCurrency)
data[].finalFiatAmount	string	Net amount (in same currency as fiatCurrency)
page	integer	Current page
pageSize	integer	Page size
total	integer	Total records

CURL Request:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/order/list' \\
--header 'Content-Type: application/json' \\
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \\
--header 'X-GatePay-Timestamp: 1769671300600' \\
--header 'x-GatePay-Nonce: 8907767296' \\
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \\
--data-raw '{
"page": 1,
"pageSize": 10
}'

Response:

{
  "code": "000000",
  "data": {
    "page": 1,
    "pageSize": 10,
    "total": 49,
    "data": [
      {
        "cryptoCurrency": "USDT",
        "fiatCurrency": "USD",
        "cryptoAmount": "10000",
        "fiatAmount": "99810.08",
        "orderId": "2016769960466059264",
        "status": "DONE",
        "createTime": 1769670404763,
        "updateTime": 1769670720469,
        "type": "SELL",
        "bankAccountId": "2897434",
        "fiatRate": "0.9981",
        "clientOrderId": "980932432"
      },
      {
        "cryptoCurrency": "USDT",
        "fiatCurrency": "USD",
        "cryptoAmount": "10000",
        "fiatAmount": "99810.08",
        "orderId": "2016768770965639168",
        "status": "DONE",
        "createTime": 1769670119407,
        "updateTime": 1769670300606,
        "type": "SELL",
        "bankAccountId": "2897434",
        "fiatRate": "0.9981",
        "clientOrderId": "980932433"
      }
    ]
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.5 Query List of Available Countries for Bank Cards

• API Description：If you need to add a bank account, you may first query the list of available countries for bank account registration.

• Data Type: JSON (content-type: application/json)

• Request Method: GET

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /withdraw/open/institution/otc/api/bank/country/list

• Authentication Method: Signature Verification

• Request Parameters:

• Response Body:

Field Name	Type	Description
data	array	Countriy List
data[].countryId	int	Country ID
data[].countryName	string	Country name
data[].countryCn	string	Country name (Chinese)

CURL Request:

curl --location --request GET 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/bank/country/list' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \

Response:

{
  "code": "000000",
  "data": [
    {
      "countryId": 260,
      "countryCn": "阿富汗",
      "countryName": "Afghanistan"
    },
    {
      "countryId": 3,
      "countryCn": "阿尔巴尼亚",
      "countryName": "Albania"
    },
    {
      "countryId": 4,
      "countryCn": "阿尔及利亚",
      "countryName": "Algeria"
    }
  ],
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.6 Create Bank Account

• API Description：A bank account must be added for OTC fiat withdrawal; the bank statement must be uploaded at the same time when adding a new bank account.

• Data Type：JSON （content-type：multipart/form-data）

• Request Method：POST

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /withdraw/open/institution/otc/api/bank/create

• Authentication Method：Signature Verification

• Request Parameters:

Field Name	Type	Required	Description
bankAccountName	string	Yes	Account holder name
bankName	string	Yes	Bank name
countryId	int	Yes	Country ID
address	string	Yes	Bank address
iban	string	Yes	IBAN
swift	string	Yes	SWIFT
remittanceLineNumber	string	No	Routing / clearing code
agentBankName	string	No	Agent bank name
agentBankSwift	string	No	Agent bank SWIFT
file	file	Yes	File stream,max size 4MB,only suppot jpg、jpeg、png; A bank statement issued within the last 3 months. The account holder's name must exactly match the name used for identity verification. If discrepancies arise due to language or other reasons, supporting documents must be provided (e.g., a bank certificate, a passport, an official name change document)

• Response Body

Field Name	Type	Description
bankAccountId	string	Bank Account ID

CURL Request:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/bank/create' \
--header 'X-GatePay-MerchantId;' \
--form 'bankAccountName="bank001"' \
--form 'bankName="bankName01"' \
--form 'countryId="260"' \
--form 'address="123"' \
--form 'iban="123213213"' \
--form 'swift="21321"' \
--form 'remittanceLineNumber="312"' \
--form 'agentBankName="213"' \
--form 'agentBankSwift="454"' \
--form 'file=@"/Downloads/bank.jpg"'

Response:

{
  "code": "000000",
  "data": {
    "bankAccountId": "2897434"
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.7 List Bank Accounts

• API Description：Returns all bank account details bound to the merchant

• Data Type: JSON (content-type: application/json)

• Request Method: GET

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /withdraw/open/institution/otc/api/bank/list

• Authentication Method: Signature Verification

• Request Parameters: （Fuzzy Query）

Field Name	Type	Required	Description
bankAccountName	string	No	Account holder name
iban	string	No	IBAN
swift	string	No	SWIFT
bankName	string	No	Bank name

• Response Body:

Field Name	Type	Description
data	array	Bank List
data[].bankAccountId	string	Bank Account ID
data[].bankAccountName	string	Account holder name
data[].bankName	string	Bank name
data[].countryId	int	Country ID
data[].countryName	string	Country Name
data[].address	string	Bank address
data[].iban	string	IBAN
data[].swift	string	SWIFT
data[].remittanceLineNumber	string	Routing / clearing code
data[].agentBankName	string	Agent bank name
data[].agentBankSwift	string	Agent bank SWIFT

CURL Request:

curl --location --request GET 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/bank/list?bankAccountName=bank001&bankName=bankName01&iban=123213213&swift=21321' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \

Response:

{
  "code": "000000",
  "data": [
    {
      "bankAccountId": 501,
      "bankAccountName": "12312",
      "bankName": "123123",
      "countryId": 260,
      "countryName": "Afghanistan",
      "address": "123123",
      "iban": "12313123",
      "swift": "123132123",
      "remittanceLineNumber": "3123123",
      "agentBankName": "",
      "agentBankSwift": ""
    },
    {
      "bankAccountId": 642,
      "bankAccountName": "testname",
      "bankName": "123123",
      "countryId": 11,
      "countryName": "Australia",
      "address": "123123",
      "iban": "UYTU****GFHG",
      "swift": "13123",
      "remittanceLineNumber": "1231",
      "agentBankName": "",
      "agentBankSwift": ""
    }
  ],
  "status": "SUCCESS",
  "errorMessage": ""
}

2.9.8 Delete Bank Account

• API Description：Deletes a specified bank account

• Data Type: JSON (content-type: application/json)

• Request Method: POST

• Request Headers:

  Field Name	Type	Required	Description
  X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
  X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
  X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
  X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
  X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /withdraw/open/institution/otc/api/bank/delete

• Authentication Method: Signature Verification

• Request Parameters:

Field Name	Type	Required	Description
bankAccountId	string	Yes	Bank Account ID

CURL Request:

curl --location --request POST 'https://openplatform.gateapi.io/withdraw/open/institution/otc/api/bank/delete' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: sTTGwlmQBGMpwaLg' \
--header 'X-GatePay-Timestamp: 1769671300600' \
--header 'x-GatePay-Nonce: 8907767296' \
--header 'x-GatePay-Signature: ec0102f15ced90319c02c8feb24ee81d0e9a701a2078c7b7fbfe68b9216611a6eaa2a67aa37d964b3cc9e491a3cfa8eee07c736d22b8d92fdd0f16e0bc316a4a' \
--data-raw '{
    "bankAccountId": 796
}'

Response:

{
  "code": "000000",
  "data": {},
  "status": "SUCCESS",
  "errorMessage": ""
}

2.10 Introduction to the Client Management Function

2.10.1 Add Client

Users create clients and record information through this interface. The name of a client is required and must be unique under the same merchant; other attributes are not required. If you need to save a wallet address, you need to confirm the network; if not, the network can be left blank. Spare fields are set by merchants according to actual business scenarios. You can use a spare field to save certain attribute of your clients, e.g., country/region/business type.

• Data Type: JSON (content-type: application/json)
• Request Method: POST
• Path: /merchant/open/institution/v1/pay/channelmanage/save
• Validation Method: Signature verification
• Request Body Content:

Field Name	Type	Required	Description
merchantChannelList	Channel Type	Yes	Client list,currently only supports adding one client record each time

Channel type

Field Name	Type	Required	Description
channelId	string	Yes	Client Name, the unique identifier of a client's identity entered by the merchant. It's unique under the same merchant and cannot be edited
desc	string	No	Client description, used for remarks
channelType	string	No	Client type; optional values: 0 or 1 (0 = Individual; 1 = Corporate)
address	string	No	Save the client's collection address; used for client withdrawals
chain	string	No	Save the client's collection network; used for client withdrawals. After getting the list of supported currencies, use the interface (/v1/pay/address/chains) to acquire the currency's chain network information
customFields	Custom Type	No	Custom field list
email	string	No	Email

Custom Type

Field Name	Type	Required	Description
code	string	No	Custom field, used to link the code of the spare field for client attribute settings on the merchant's dashboard
name	string	Yes	Custom field, name of the spare field
value	string	Yes	Custom field, value of the spare field

Request Example:

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/pay/channelmanage/save' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'
--data '{
    "merchantChannelList": [
        {
            "channelId": "test",
            "desc": "remarks",
            "channelType": "0",
            "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
            "chain": "ETH",
            "customFields": [
                {
                    "code": "customCode",
                    "name": "customName",
                    "value": "customValue"
                }
            ]
        }
    ]
}'

Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": ""
}

Response Fields:

Field Name	Type	Required	Description
status	string	Yes	SUCCESS or FAIL
code	string	Yes	Error code
errorMessage	string	No	Error message

2.10.2 Query Client

Query information about the current merchant's client list.

• Data Type: JSON (content-type: application/json)
• Request Method: GET
• Path: /merchant/open/institution/v1/pay/channelmanage/list
• Validation Method: Signature verification
• Request Body Content:

Field Name	Type	Required	Description
channelId	string	No	Client Name; fuzzy query
desc	string	No	Client description; fuzzy query
channelType	string	No	Client type; optional values: 0 or 1 (0 = Individual; 1 = Corporate)
page	int	Yes	No. of the start page
count	int	Yes	Number of records per page

Request Example:

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/pay/channelmanage/list' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'
--data '{
    "page": 1,
    "count":10
}'

Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
  "data": {
    "total": 217,
    "merchantChannelList": [
      {
        "channelId": "test",
        "desc": "remarks",
        "channelType": "0",
        "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
        "chain": "ETH",
        "createTime": "1735568326554",
        "updateTime": "1735568326554",
        "customFields": [
          {
            "code": "customCode",
            "name": "customName",
            "value": "customValue"
          }
        ]
      }
    ]
  }
}

Response Fields:

Field Name	Type	Description
status	string	SUCCESS or FAIL
code	string	Error code
errorMessage	string	Error message
data	Data Type	Error message

Data Type

Field Name	Type	Description
total	int64	Total number of records
merchantChannelList	Channel Type	Client list

Channel type

Field Name	Type	Description
channelId	string	Client Name
desc	string	Client description
channelType	string	Client type
address	string	The client's collection address
chain	string	The client's collection network
customFields	Custom Type	Custom field list
email	string	Email

Custom Type

Field Name	Type	Description
code	string	Custom field
name	string	Custom field
value	string	Custom field

2.10.3 Edit Client

Users edit clients and record information through this interface. The name of a client is required and must be unique under the same merchant; other attributes are not required. If you need to save a wallet address, you need to confirm the network; if not, the network can be left blank. Spare fields are set by merchants according to actual business scenarios. You can use a spare field to save certain attribute of your clients, e.g., country/region/business type.

• Data Type: JSON (content-type: application/json)
• Request Method: PUT
• Path: /merchant/open/institution/v1/pay/channelmanage/update
• Validation Method: Signature verification
• Request Body Content:

Field Name	Type	Required	Description
merchantChannelList	Channel Type	Yes	Client list,currently only supports editing one client record each time

Channel type

Field Name	Type	Required	Description
channelId	string	Yes	Client Name, the unique identifier of a client's identity entered by the merchant. It's unique under the same merchant and cannot be edited
desc	string	No	Client description, used for remarks
channelType	string	No	Client type; optional values: 0 or 1 (0 = Individual; 1 = Corporate)
address	string	No	Save the client's collection address; used for client withdrawals
chain	string	No	Save the client's collection network; used for client withdrawals. After getting the list of supported currencies, use the interface (/v1/pay/address/chains) to acquire the currency's chain network information
customFields	Custom Type	No	Custom field list
email	string	No	Email

Custom Type

Field Name	Type	Required	Description
code	string	No	Custom field, used to link the code of the spare field for client attribute settings on the merchant's dashboard
name	string	Yes	Custom field, name of the spare field
value	string	Yes	Custom field, value of the spare field

Request Example:

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/pay/channelmanage/update' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'
--data '{
    "merchantChannelList": [
        {
            "channelId": "test",
            "desc": "remarks",
            "channelType": "0",
            "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
            "chain": "ETH",
            "customFields": [
                {
                    "code": "customCode",
                    "name": "customName",
                    "value": "customValue"
                }
            ]
        }
    ]
}'

Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": ""
}

Response Fields:

Field Name	Type	Required	Description
status	string	Yes	SUCCESS or FAIL
code	string	Yes	Error code
errorMessage	string	No	Error message

2.10.4 Delete Client

Delete information about a client.

• Data Type: JSON (content-type: application/json)
• Request Method: DELETE
• Path: /merchant/open/institution/v1/pay/channelmanage/delete
• Validation Method: Signature verification
• Request Body Content:

Field Name	Type	Required	Description
channelId	string	Yes	Client Name

Request Example:

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/pay/channelmanage/delete' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--header 'X-GatePay-On-Behalf-Of: 2124538349'
--data '{
    "channelId": "test"
}'

Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": ""
}

Response Fields:

Field Name	Type	Required	Description
status	string	Yes	SUCCESS or FAIL
code	string	Yes	Error code
errorMessage	string	No	Error message

2.10.5 Steps for Merchants to Access the Cashier

Gate Pay's Preparation for Accessing

Please refer to Gate Pay Access Preparation

Get Chain Information for Address Payment

To call the add client interface (/merchant/open/institutiont/v1/pay/channelmanage/save), merchants need to provide the chain and chain network information. The process is as follows.

1. Use the interface (/v1/pay/address/currencies) to query the list of supported currencies for the address payment.
2. Then use the interface (/v1/pay/address/chains) to acquire the currency's chain network information.

FAQ

Q: Why does the prompt say the client name's returned parameter is illegal?

A: The client name should be no longer than 50 characters. It supports Chinese characters, numbers, uppercase and lowercase letters, and special characters such as "_", "/", "|", and "-". Spaces are not allowed.

Q: Why did I fail to delete a client?

A: Because the current client is being used by payment products. You need to ensure payment products (address payment and static collection QR codes) are not using this client (Delete the corresponding collection QR code or wait for it to become expired).

## 2.11 Wealth management

2.11.1 Operating status of wealth management services

• Data type：JSON （content-type：application/json）

• HTTP method：POST

• Request Headers:

Field Name	Type	Required	Description
X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /merchant/open/institution/v1/wealth/action

• Authentication: Signature verification

• Request body:

  Field Name	Type	Required	Description
  action	string	Yes	Operation type: CANCEL-Close; SIGN-Open

• Response body

  Field Name	Type	Required	Description
  account_id	string	Yes	Subaccount ID
  status	string	Yes	Operation type: CANCEL-Close; SIGN-Open

• CURL Request

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/wealth/action' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1740019013818' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'x-GatePay-Nonce: 9722139164' \
--header 'x-GatePay-Signature: 8504fe097f7297f8952c76e628ce59dbc93d1df64c95f26c73140ef365d4aa1471826ada0534315461682ec35c131d7e133c51d2ab0822fe7366650a111887ba' \
--data '{
    "action":"SIGN"
}'

• Response

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "status": "SIGN",
        "account_id": "2124766106"
    }
}

2.11.2 Check the status of wealth management services

• Data type：JSON （content-type：application/json）

• HTTP method：GET

• Request Headers:

Field Name	Type	Required	Description
X-GatePay-Certificate-ClientId	string	Yes	The clientId assigned when the merchant registers an application in the Gate merchant console.
X-GatePay-Timestamp	string	Yes	UTC timestamp in milliseconds when the request is generated. GatePay will not process requests where the difference from the receive time exceeds 10 seconds.
X-GatePay-Nonce	string	Yes	Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.
X-GatePay-On-Behalf-Of	string	Yes	ID of the institution account on whose behalf the request is sent.
X-GatePay-Signature	string	Yes	Request signature. GatePay uses this signature to verify whether the request is valid.

• Path: /merchant/open/institution/v1/wealth/query

• Authentication: Signature verification

• Response body

  Field Name	Type	Required	Description
  account_id	string	Yes	Subaccount ID
  status	string	Yes	Wealth Status: Closed-Cancel Open-Sign
  enabled	long	Yes	Startup time (milliseconds)
  updated	string	Yes	Update time (milliseconds)

• CURL Request

curl --location 'https://openplatform.gateapi.io/merchant/open/institution/v1/wealth/query' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1740018611625' \
--header 'X-GatePay-On-Behalf-Of: 2124538349' \
--header 'x-GatePay-Nonce: 3347302609' \
--header 'x-GatePay-Signature: 7209e852c0fca24a9430d097f93331b7d2bac82b2710763a73af67340b67c2d8fef524051d30a3ff42258a93a200b08fdd5849ec2d2fa0f7c7ba9ed52ce38010'

• Response

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "status": "SIGN",
        "enabled": 1772516898675,
        "updated": 1772519811822,
        "account_id": "2124766106"
    }
}

3. Error Codes

3.1 Account

Error Code	Description	Resolution
400001	Invalid request parameters	Please check whether the request parameters are valid
400002	Invalid signature	Verify that the signature algorithm and value are correct
400003	Request timestamp expired	Check the timestamp field in the request header
550226	The sub-account for this request_id already exists	Check whether the request_id has already been used to create a sub-account
550227	No sub-account matches the query conditions	Check the query parameters

3.2 Order Placement

Error Code	Description	Resolution
550142	X-GatePay-On-Behalf-Of is missing in the request header	Pass the proxied institution account ID correctly
550200	The main account does not have permission to act on the proxied account	Create / grant the delegated-account permission
550201	The asset currency for the queried account balance does not exist	Use the correct asset currency to query

3.3 Otc Withdraw

Error Code	Description	Solution
400001	Invalid request parameters	Check if the request parameters are valid
400002	Signature verification failed	Check if the merchant signature is correct
400003	Request timestamp expired	Check the timestamp field in the request header
400004	API credential does not exist or is invalid	Check if the API credential exists or is valid
400611	Insufficient balance	Check the account balance
550175	Order does not exist	Check if the order was initiated or if the order ID is correct
5503001	API rate limit exceeded	Retry later
5502961	Service unavailable in user's country	Check if the service is allowed in the user's country
5502971	User is not eligible for OTC trading	Check the user's OTC trading eligibility
5502761	ClientOrderId is duplicated	Change clientOrderId
550018	Rejected by risk control	Retry later
400000	Unknown error	Internal system error
550301	The user has not completed the relevant Global OTC authentication	-
550302	The user has not completed the individual OTC professional certification application	-
550303	The user has not completed the enterprise OTC professional certification application	-
550304	The user's OTC professional certification application has been rejected	-
550305	The user's OTC professional certification has been frozen	-
550306	The user's professional certification is under review	-
550307	The user's transaction limit is insufficient, an application for limit increase is required	-
550308	The user's limit increase application is under review	-
550309	The limit increase application has been rejected, please reapply	-
550310	The user has not bound a bank card	Please bind a bank account and try again
550311	The current operation is restricted, please contact customer service for handling	-
550312	Cryptocurrency withdrawal is prohibited	-
550313	The inquiry has expired	Please requote and place the order with the new token
550314	idempotency check failed	-
550315	Amount out of range	Please adjust the quotation amount. For details, contact customer service
550316	Create bank account failed	-
550317	Delete bank account failed	-
550318	Invalid promotion code	Please use a valid promotion code