法币对账单下载
大约 2 分钟
请求
按账单日下载商户法币对账文件。文件与商户后台账单同源,返回一个有时效的下载地址。
强制 IP 白名单
本接口强制校验请求 IP 白名单,与是否勾选「代收 / 代付 / 订单查询 / 余额查询」无关。
请把调用方的出口公网 IP 配到商户后台「请求 IP 白名单」。名单为空,或出口 IP 不在名单中,返回 1001。
请求路径
POST。本接口没有沙箱地址。
生产:
https://openapi.toppayment.com/{国家编码}/reconciliation/v1/download
| 国家/地区 | 国家码 | 生产 |
|---|---|---|
| 菲律宾 | ph | https://openapi.toppayment.com/ph/reconciliation/v1/download |
| 印度尼西亚 | id | https://openapi.toppayment.com/id/reconciliation/v1/download |
| 尼日利亚 | ng | https://openapi.toppayment.com/ng/reconciliation/v1/download |
| 印度 | in | https://openapi.toppayment.com/in/reconciliation/v1/download |
| 泰国 | th | https://openapi.toppayment.com/th/reconciliation/v1/download |
| 越南 | vn | https://openapi.toppayment.com/vn/reconciliation/v1/download |
| 秘鲁 | pe | https://openapi.toppayment.com/pe/reconciliation/v1/download |
| 巴西 | br | https://openapi.toppayment.com/br/reconciliation/v1/download |
| 墨西哥 | mx | https://openapi.toppayment.com/mx/reconciliation/v1/download |
| 哥伦比亚 | co | https://openapi.toppayment.com/co/reconciliation/v1/download |
| 玻利维亚 | bo | https://openapi.toppayment.com/bo/reconciliation/v1/download |
| 巴基斯坦 | pk | https://openapi.toppayment.com/pk/reconciliation/v1/download |
| 孟加拉 | bd | https://openapi.toppayment.com/bd/reconciliation/v1/download |
| 土耳其 | tr | https://openapi.toppayment.com/tr/reconciliation/v1/download |
请求头参数
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | 固定值:application/json |
请求体参数
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| mchNo | M | String(32) | 商户编号 |
| date | M | String(10) | 账单日,格式 yyyy-MM-dd只能查昨天及更早。当天、未来日期返回 1005 |
| timestamp | M | String(13) | 请求时间戳(13 位毫秒),偏差须在 ±5 分钟内 |
| sign | M | String | 签名,见 签名规则 参与签名的字段只有 date、mchNo、timestamp |
请求示例
Content-Type: application/json
{
"mchNo": "{{mchNo}}",
"date": "2026-11-09",
"timestamp": "1749102949784",
"sign": "按签名规则生成后替换"
}
响应
响应体参数
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| success | M | Boolean | 是否成功 |
| code | M | String | 9999 成功;其他见 异常码 |
| msg | O | String | 失败原因,成功时为 null |
| timeStamp | M | Number | 服务器响应时间(毫秒) |
| data | M | Object | 成功时返回 |
| date | M | String | 账单日 |
| downloadUrl | M | String | 对账文件下载地址,1 小时内有效 |
响应示例
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767873172906,
"data": {
"date": "2026-11-09",
"downloadUrl": "https://storage.googleapis.com/example/assetRecord/bill.csv?X-Goog-Expires=3600"
}
}
常见错误
| 异常码 | 说明 |
|---|---|
| 0001 | 参数错误,例如 date 不是 yyyy-MM-dd,或时间戳超出窗口 |
| 0002 | 签名失败 |
| 1001 | IP 白名单未通过。出口 IP 未配置,或名单为空 |
| 1005 | 对账文件不存在。账单日是当天或未来,或当天没有可出账的资金变动 |
