Skip to main content

get transaction report

for automated reconciliation and accounting, divit compiles transaction reports in standard Excel format (.xlsx). two cadences are available and both are retrievable programmatically via our reporting API using your merchant API key:

  • daily report — one report per calendar day
  • monthly report — one report per calendar month

each report is generated per currency, so the currency code is part of the filename.

daily report​

endpoint details​

  • HTTP method: GET
  • production URL: https://api.divit.com.hk/reporting/paynow/daily/report/{filename}
  • sandbox URL: https://sandbox-api.divit.dev/reporting/paynow/daily/report/{filename}

{filename} format​

the target filename must follow this pattern:

{MERCHANT_SHORTCODE}-{yyyy-mm-dd}-{CURRENCY}-divit-daily-transaction.xlsx
  • MERCHANT_SHORTCODE: the unique abbreviation representing your organization. you can retrieve this code under your profile in the divit merchant portal.
  • yyyy-mm-dd: the target calendar date for the report.
  • CURRENCY: the 3-letter ISO currency code of the report (e.g. HKD).

example filename: MERCHANTX-2024-02-26-HKD-divit-daily-transaction.xlsx

generation schedule

daily reports are automatically generated each morning (HKT) for the previous calendar day. if there were no transactions processed on the requested day, or if you request a report before it has been generated, the server returns a JSON error with code 8100 (see response formats below).

monthly report​

endpoint details​

  • HTTP method: GET
  • production URL: https://api.divit.com.hk/reporting/paynow/monthly/report/{filename}
  • sandbox URL: https://sandbox-api.divit.dev/reporting/paynow/monthly/report/{filename}

{filename} format​

the target filename must follow this pattern:

{MERCHANT_SHORTCODE}-{yyyy-mm}-{CURRENCY}-divit-monthly-transaction.xlsx
  • MERCHANT_SHORTCODE: the unique abbreviation representing your organization. you can retrieve this code under your profile in the divit merchant portal.
  • yyyy-mm: the target calendar month for the report.
  • CURRENCY: the 3-letter ISO currency code of the report (e.g. HKD).

example filename: MERCHANTX-2024-02-HKD-divit-monthly-transaction.xlsx

generation schedule

monthly reports are automatically generated on the 1st of each month (from around 06:30 HKT) for the previous full calendar month. if there were no transactions processed during that month, or if you request a report before it has been generated, the server returns a JSON error with code 8100 (see response formats below).

request headers​

both endpoints authenticate with your merchant API key and return the file scoped to your own merchant only:

api-key: your_api_key_here
Content-Type: application/json

implementation example (download & file save)​

below is an implementation example using Node's modern fetch API to download a report file and save it securely on the filesystem. the same function works for both cadences — pass the daily or monthly URL:

const fs = require('fs');

/**
 * downloads a transaction report from divit (daily or monthly)
 * @param {string} url - full report URL, e.g.
 *   https://sandbox-api.divit.dev/reporting/paynow/daily/report/{filename}
 *   https://sandbox-api.divit.dev/reporting/paynow/monthly/report/{filename}
 * @param {string} apiKey - your secret merchant API key
 * @param {string} savePath - path where the file should be saved
 */
async function downloadTransactionReport(url, apiKey, savePath) {
  try {
    const response = await fetch(url, {
      method: "GET",
      headers: {
        "api-key": apiKey,
        "Content-Type": "application/json"
      }
    });

    if (!response.ok) {
      // handle JSON error response (e.g. file not found)
      const errorData = await response.json();
      throw new Error(`API Error [${errorData.code}]: ${errorData.message}`);
    }

    // retrieve file binary buffer and write to file system
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(arrayBuffer);
    fs.writeFileSync(savePath, buffer);
    console.log(`report successfully downloaded and saved to: ${savePath}`);
  } catch (error) {
    console.error("failed to download transaction report:", error.message);
    throw error;
  }
}

response formats​

successful retrieval (spreadsheet binary)​

if the report file is found, our server returns an HTTP 200 OK status with raw binary buffer data and the following content headers:

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename=MERCHANTX-2024-02-26-HKD-divit-daily-transaction.xlsx

report not found (JSON error)​

if the report does not exist — no transactions for the period, or the report has not been generated yet — the server returns a JSON error structure with code 8100:

{
  "code": 8100,
  "message": "failed to find file MERCHANTX-2024-02-26-HKD-divit-daily-transaction.xlsx"
}