Open API Reference for Bluepay

# 对账文件下载

# 说明

  • 本接口为对账文件下载的统一入口。
  • /report/download 返回的是最终 GPG 加密压缩包的 OSS 下载链接。
  • 最终文件标准格式为 zip.gpg，压缩包内包含：
    • 交易明细对账文件
    • 对账汇总清单文件
  • 收到结算回款通知 V2 后，可再调用本接口下载最新对账文件。

# 请求URL

  • {domain}/open-api/report/download

# 请求方式

  • POST

# 请求头

参数名 必选 类型 说明
Content-Type 是 string application/json

# 请求体参数

参数名 必选 类型 说明
appId 是 string 应用 APPID
param 是 string 参数体
sign 是 string 签名

# param参数

参数名 必选 类型 长度限制 示例 说明
countryCode 是 string 1-32 TH 国家编码
transDate 是 string - 2026-05-20 交易日期
transType 是 integer - 2 交易类型。仅支持 1=代付，2=代收
timestamp 是 long - 1747728000 当前时间戳

# 请求示例

# 请求体

{
  "appId": "349094b672f347969422ca70123790477a8af",
  "sign": "p69kDdBZHWd08EGxk8GQp0q/jTz0iEzmp2P5fSWEjc4iTZugjGm4yS5B0VwYuxfbujPatPItqNOLGokTOdBWZ+zjwxHN0RylNsDhmQW7UGDZ+SrtC72tDVZy2bRm8fa9vVOA8SgS1rNZDfyGT+7gB5m6fn6jLl6+lsGXUuE+LZf+WG7rFtewgR6MTuavEI7PQg0piAx5ypS0dWyOlL6nqGP7w5ZnV6FV23JLuKVLpj/+kJ28GtIh7EHrg1/3JF6R2GodjzPCZQj8y9QS/K1IrJ1CIXU3UvHT2gvzIaiEInlivb5u4fYQEMvx7lpHt+xyJQYpFU/lX6pFLsKe/rGZcA==",
  "param": "{\"countryCode\":\"TH\",\"transDate\":\"2026-05-20\",\"transType\":2,\"timestamp\":1747728000}"
}

如何构造请求体

# 响应参数

参数名 类型 说明
code integer 响应码
message string 响应信息
data object 数据

# data参数

参数名 类型 说明
downloadUrl string 最终 GPG 加密压缩包的 OSS 下载链接，文件格式为 .zip.gpg

# 响应示例

响应码集合

{
  "code": 10000,
  "message": "Success",
  "data": {
    "downloadUrl": "https://calf.oss-cn-hongkong.aliyuncs.com/money/payment/report/Settlement_C0322mepg6dM_20260520_20260521153939.zip.gpg?Expires=1779263999&OSSAccessKeyId=example&Signature=example"
  }
}

# 文件说明

  • downloadUrl 返回的文件为最终交付文件。
  • zip.gpg 解密后得到 zip 压缩包，压缩包内通常包含：
    • yyyyMMdd_Payment_{merchantNo}_{countryCode}_{currency}.xlsx 或 .csv
    • summary_{merchantName}_{yyyyMMddHHmmss}.xlsx 或 .csv
  • 最终加密压缩包文件名通常为 Settlement_{merchantNo}_{yyyyMMddHHmmss}.zip.gpg
  • 交易明细文件与对账汇总清单文件使用相同报表格式，默认 xlsx

# 交易明细对账文件

# 文件标题

  • 首行为标题行
  • 当前导出标题按以下字段名输出
标题 字段内容
merchantOrderId 商户订单号
transactionId 平台交易流水号
paymentChannel 收款渠道编码
amount 交易金额，按交易币种主单位输出
fee 商户手续费，按交易币种主单位输出
name 付款人姓名
mobile 付款人手机号
status 交易状态。可能值包括 Unpaid、Success、Failed、Voided、Voiding
createTime 交易创建时间
completeTime 交易完成时间
country 交易国家编码
settlementStatus 结算状态。当前可能值包括 Settled、Pending
projectType 项目类型。当前可能值包括 PPCASH、VIP、HOME、COD
estimatedSettlementTime 预计结算时间
actualSettlementTime 实际结算时间
withdrawReturnTime 结算回款完成时间
remark 备注信息

# 对账汇总清单文件

# 文件标题

  • 首行为标题行
  • 当前导出标题固定如下
标题 字段内容
fileName 交易明细对账文件名
recordCount 交易明细记录总数
totalTransAmount 交易总金额，按交易币种主单位汇总
totalMerchantFee 商户手续费总金额，按交易币种主单位汇总
settleCompleteTime 全部明细完成结算后的最晚结算完成时间；若当日明细未全部结算完成则为空
withdrawCompleteTime 全部结算回款完成后的最晚回款完成时间；若当日明细未全部完成回款则为空

# GPG 公钥要求

J&T 生产环境对账文件使用 GPG 公钥加密。上线前，J&T 需要向 Bluepay 提供可导入的 GPG 公钥。

公钥要求如下：

  • 请提供 ASCII Armor 格式公钥文件，推荐扩展名 .asc 或 .pub
  • 密钥类型：RSA and RSA
  • 密钥长度：4096
  • 过期时间：建议设置为 1年 或 永久不过期
  • 请同时提供公钥指纹信息，方便双方核验
  • 只提供公钥，不要提供私钥
  • 请务必妥善保管私钥及其 passphrase，后续文件解密需要使用

公钥元数据示例：

pub   rsa4096 2026-05-20 [SC]
      7A7A7F4A89A38BD2F3EBD0123C5052BE9BDB62AD
uid           [ultimate] J&T (123) <j&t@test.com>
sub   rsa4096 2026-05-20 [E]

# GPG 加解密说明

  • Bluepay 使用 OpenPGP / GPG 兼容格式加密对账压缩包
  • 下载得到的 .zip.gpg 文件可直接用 gpg 工具解密

# 校验文件摘要

macOS:

shasum -a 256 Settlement_C0322mepg6dM_20260520_20260521153939.zip.gpg

Linux:

sha256sum Settlement_C0322mepg6dM_20260520_20260521153939.zip.gpg

# 解密文件

gpg --output Settlement_C0322mepg6dM_20260520_20260521153939.zip --decrypt Settlement_C0322mepg6dM_20260520_20260521153939.zip.gpg

# 解压文件

unzip Settlement_C0322mepg6dM_20260520_20260521153939.zip

# 注意事项

  • Bluepay 标准返回格式为加密压缩包下载链接。
  • 请确保 J&T 已完成 GPG 私钥保管、解密验证和灾备备份。
  • 若公钥未提前配置完成，生产环境无法按约定输出加密对账文件。

← 结算回款通知 →