1. Introduction

​ Merchants can query the transaction history of their payment accounts through this API. It supports pagination to handle large volumes of data, filtering by time range, and precise searches by financial type, order ID, currency, and other fields. This helps merchants efficiently reconcile funds and manage their finances.

2. API Interface

2.1 Retrieve Transaction History

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

• Method：GET

• Path: /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), 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

CURL Request

curl --location 'http://dev.halftrust.xyz/gfpay/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'

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"
            }
        ]
    }
}

3. Error Code

Error Code	Description	Solution
400007	Unsupported mediatype	Check the mediatype supported by the API
400001	Invalid request parameter	Verify that the request parameters are valid
400002	Invalid signature	Check that the signature algorithm is correct
5504060	Invalid OrderType parameter	Valid order types for query: 1-Merchant order ID 2-GatePay order ID 3-Transaction history order ID
5504061	Query count exceeds 500	Set the parameters to a reasonable value