Open API Reference for Bluepay

# Report Download

# Description

  • This interface is the unified entry for reconciliation file download.
  • /report/download returns the OSS download URL of the final GPG-encrypted package.
  • The standard final file format is zip.gpg. The package contains:
    • transaction detail reconciliation file
    • reconciliation summary file
  • After receiving Settlement Notification V2, you can call this interface again to download the latest reconciliation package.

# URL

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

# Method

  • POST

# Request Header

Parameter name Required Type Description
Content-Type Yes string application/json

# Request parameters

Parameter name Required Type Description
appId Yes string appId
param Yes string param
sign Yes string sign

# param

Parameter name Required Type Length Example Description
countryCode Yes string 1-32 TH country code
transDate Yes string - 2026-05-20 transaction date
transType Yes integer - 2 transaction type. Only 1=disbursement, 2=payment are supported
timestamp Yes long - 1747728000 current timestamp

# Request example

# Request body

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

How to construct request body

# Response parameters

Parameter name Type Description
code integer response code
message string response message
data object response data

# data

Parameter name Type Description
downloadUrl string OSS download URL of the final GPG-encrypted package, file format is .zip.gpg

# Response example

Code collection

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

# File description

  • downloadUrl points to the final delivery file.
  • After decrypting the zip.gpg file, you will get a zip package. The package usually contains:
    • yyyyMMdd_Payment_{merchantNo}_{countryCode}_{currency}.xlsx or .csv
    • summary_{merchantName}_{yyyyMMddHHmmss}.xlsx or .csv
  • The final encrypted package name is usually Settlement_{merchantNo}_{yyyyMMddHHmmss}.zip.gpg
  • The transaction detail file and summary file use the same report format, default xlsx

# Transaction Detail Reconciliation File

# Header row

  • The first row is the header row
  • The current export headers are the following field names
Header Field content
merchantOrderId merchant order ID
transactionId platform transaction ID
paymentChannel payment channel code
amount transaction amount in major currency unit
fee merchant fee in major currency unit
name payer name
mobile payer mobile number
status transaction status. Current values include Unpaid, Success, Failed, Voided, Voiding
createTime transaction creation time
completeTime transaction completion time
country transaction country code
settlementStatus settlement status. Current values include Settled, Pending
projectType project type. Current values include PPCASH, VIP, HOME, COD
estimatedSettlementTime estimated settlement time
actualSettlementTime actual settlement time
withdrawReturnTime settlement remittance completion time
remark remark information

# Reconciliation Summary File

# Header row

  • The first row is the header row
  • The current export headers are fixed as below
Header Field content
fileName transaction detail reconciliation file name
recordCount total record count in the detail file
totalTransAmount total transaction amount in major currency unit
totalMerchantFee total merchant fee in major currency unit
settleCompleteTime latest settlement completion time after all detail records are settled; empty if not all records are settled
withdrawCompleteTime latest remittance completion time after all settlements are remitted; empty if not all records are remitted

# GPG public key requirements

J&T production reconciliation files are encrypted with a GPG public key. Before go-live, J&T must provide an importable GPG public key to Bluepay.

Requirements:

  • Please provide the public key in ASCII armor format, recommended extension .asc or .pub
  • Key type: RSA and RSA
  • Key length: 4096
  • Expiration time: 1 year or permanent is recommended
  • Please provide the key fingerprint for both-side verification
  • Only provide the public key, never provide the private key
  • Please make sure the private key and its passphrase are kept safely, because they are required for file decryption

Public key metadata example:

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

# GPG decrypt and extract guide

  • Bluepay uses OpenPGP / GPG compatible encryption for the reconciliation package
  • The downloaded .zip.gpg file can be decrypted directly with gpg

# Verify checksum

macOS:

shasum -a 256 Settlement_C0322mepg6dM_20260520_20260521153939.zip.gpg

Linux:

sha256sum Settlement_C0322mepg6dM_20260520_20260521153939.zip.gpg

# Decrypt file

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

# Unzip file

unzip Settlement_C0322mepg6dM_20260520_20260521153939.zip

# Notes

  • The standard Bluepay response format is an encrypted package download URL.
  • Please make sure J&T has completed private key storage, decryption verification, and backup.
  • If the public key is not configured before go-live, the production environment cannot deliver the encrypted reconciliation file as agreed.

← Settled Notification →