1. 功能介绍

​ 允许商家查询其支付账户的资金流水记录。支持分页查询以应对大数据量，能够根据时间范围筛选记录，并支持按财务类型、订单号、币种等字段进行精确查询。该接口帮助商家便捷地进行资金对账和财务管理。

2. API 接口

2.1 获取资金流水账单

• 数据类型：JSON （content-type：application/json）

• 请求⽅式：GET

• 路径Path: /v1/pay/bill/orderlist

• 验证方式：签名验证

• 请求体内容:

字段名	类型	是否必须	说明
startTime	int64	是	开始时间，单位毫秒
endTime	int64	是	结束时间，单位毫秒
page	int	是	分页编号，从1开始
count	int	是	获取一页条数，最大500
currency	string	否	搜索币种
financialType	string	否	财务类型：参考财务类型定义
orderType	int	否	查询订单类型: 1-商户订单号 2-GatePay订单号 3-资金流水订单号
orderIdNo	string	否	查询单号

响应内容

字段名	类型	说明
total	int	总记录数
hasNext	bool	是否有下一页 true: 表示有 false:表示没有
nextPage	int	下一页page编号,当hasNext为true该字段才有效
balance_history_item_list	array	响应的列表数据,数组类型

balance_history_item_list响应字段定义:

字段名	类型	说明
transactId	string	支付流水单号
transactTime	int64	入账时间，毫秒时间戳
orderId	string	GatePay订单号
merchantTradeNo	string	商户订单号
financialType	string	财务类型
payAmount	string	收支金额
currency	string	收支币种
balance	string	账户余额
balanceCurrency	string	账户余额币种
status	string	PAID表示成功
payer	Int64	Gate 支付付款用户UID
buyer	string	对方信息: Web3支付该值付款地址 非Web3支付为付款人UID
refund_gate_id	string	退款订单ID
payChannel	string	支付方式: Web3 支付 Gate 支付
fullChain	string	支付网络全称
address	string	商家收款地址
hash	string	交易Hash

CURL 请求

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'

响应:

{
    "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

错误码	描述	解决方案
400007	不⽀持的media type	查看接⼝⽀持的media type
400001	无效请求参数	请检查请求参数是否合法
400002	无效签名	检查签名算法是否正确
5504060	请求参数OrderType类型错误	查询订单类型如下: 1-商户订单号 2-GatePay订单号 3-资金流水订单号
5504061	单次查询数量条数不能超过500条	请设置合理的参数