get settlement report

settlement reports provide detailed ledgers of bank transfers made from divit's escrow accounts directly to your corporate bank account. unlike daily transaction reports, which track purchase intents, settlement reports map directly to physical bank disbursements.

acquiring a settlement report is a two-step process:

1. query the settlement list: fetch a catalog of available report filenames matching your target dates.
2. download the file: retrieve the Excel spreadsheet using the target filename.

---

step 1: fetch available settlement reports

query our reporting database to locate reports compiled within your desired timeframe.

endpoint details

• HTTP method: GET
• production URL: https://api.divit.com.hk/reporting/settlement/report
• sandbox URL: https://sandbox-api.divit.dev/reporting/settlement/report

query parameters

Parameter	Type	Required	Description
fromDate	string	Yes	target date in yyyy-mm-dd format (e.g., 2024-02-26).
toDate	string	No	end range date in yyyy-mm-dd format.

implementation example (list reports)

/**
 * queries available settlement reports from a given date
 * @param {string} fromDate - starting date (yyyy-mm-dd)
 * @param {string} apiKey - your secret merchant API key
 * @returns {Promise<object>} - JSON catalog list of reports
 */
async function fetchSettlementReports(fromDate, apiKey) {
  const url = `https://sandbox-api.divit.dev/reporting/settlement/report?fromDate=${fromDate}`;

  try {
    const response = await fetch(url, {
      method: "GET",
      headers: {
        "api-key": apiKey,
        "Content-Type": "application/json"
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP Error: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error("failed to fetch settlement list:", error);
    throw error;
  }
}

JSON response catalog example

{
  "code": 0,
  "message": "OK",
  "data": [
    {
      "reportDate": "2024-02-26T00:00:00Z",
      "platform": "production",
      "type": "settlement/orders",
      "title": "settlement report for YOUMALL-20240226-E364",
      "merchantID": "4303c954-afbf-463c-ae37-bdcff2ac106a",
      "abbreviation": "YOUMALL",
      "currency": "HKD",
      "bucket": "divit_reporting",
      "path": "settlements/production",
      "filename": "4303c954-afbf-463c-ae37-bdcff2ac106a-settlement-report.xlsx",
      "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "numOfRecords": 99,
      "createdAt": "2024-02-26T02:35:33.041243Z",
      "updatedAt": "2024-02-26T02:35:33.041243Z"
    }
  ]
}

---

step 2: download settlement report spreadsheet

use the filename value extracted from step 1 to download the binary excel sheet.

endpoint details

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

implementation example (download & file save)

const fs = require('fs');

/**
 * downloads a binary settlement spreadsheet and saves it locally
 * @param {string} filename - target report filename
 * @param {string} apiKey - your secret merchant API key
 * @param {string} savePath - destination file path
 */
async function downloadSettlementReport(filename, apiKey, savePath) {
  const url = `https://sandbox-api.divit.dev/reporting/settlement/report/${filename}`;

  try {
    const response = await fetch(url, {
      method: "GET",
      headers: {
        "api-key": apiKey,
        "Content-Type": "application/json"
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API Error [${errorData.code}]: ${errorData.message}`);
    }

    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(arrayBuffer);
    fs.writeFileSync(savePath, buffer);
    console.log(`settlement report successfully saved to: ${savePath}`);
  } catch (error) {
    console.error("failed to download settlement report:", error.message);
    throw error;
  }
}

---

response formats

successful retrieval (spreadsheet binary)

upon success, the server returns the spreadsheet binary content:

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename=4303c954-afbf-463c-ae37-bdcff2ac106a-settlement-report.xlsx

report not found (JSON error)

settlement schedule & banking holidays

• settlement reports are compiled automatically as soon as the inter-bank fund transfer settles.
• banking holidays: real-time settlements and inter-bank clearings do not execute on bank holidays or weekends. hence, no reports will be compiled during these periods.
• if you query a filename before its generation, our server returns error code 8100:

{
  "code": 8100,
  "message": "failed to find file 4303c954-afbf-463c-ae37-bdcff2ac106a-settlement-report.xlsx"
}