Settlements

KINGSTONE generates daily settlement reports that summarize all spin activity for your partner account. These reports are the foundation of financial reconciliation between you and KINGSTONE.

How Settlements Work

1. Report generation — Every day at 02:00 UTC, KINGSTONE compiles all spin activity from the previous day into a settlement report.
2. Partner review — You fetch the report and compare the numbers against your own records.
3. Acknowledge or dispute — If the numbers match, acknowledge the report. If there is a discrepancy, dispute it with a reason.

Report Contents

Each settlement report includes:

Field	Description
reportDate	The date this report covers (YYYY-MM-DD)
totalSpins	Total number of spins across all games
totalWageredUsd	Total amount wagered in USD
totalPaidOutUsd	Total amount paid out in USD
netPositionUsd	Net position (wagered minus paid out)
ggrUsd	Gross Gaming Revenue in USD
gameBreakdown	Per-game breakdown with individual totals
integrityHash	SHA-256 hash of the report data for tamper detection
reportStatus	Current status: PENDING, GENERATED, ACKNOWLEDGED, or DISPUTED

Listing Settlement Reports

Fetch your most recent reports with pagination:

import { KingstoneClient } from '@kingstone/sdk';

const client = new KingstoneClient({
  apiKey: 'ks_sandbox_your_key_here',
  sandbox: true,
});

const { reports, total } = await client.listSettlements({
  page: 1,
  limit: 10,
});

console.log(`${total} total reports`);
for (const report of reports) {
  console.log(`${report.reportDate}: ${report.totalSpins} spins, GGR $${report.ggrUsd.toFixed(2)} — ${report.reportStatus}`);
}

Getting a Single Report

Fetch a specific report by date:

const report = await client.getSettlement('2026-03-23');

console.log(`Date: ${report.reportDate}`);
console.log(`Spins: ${report.totalSpins}`);
console.log(`Wagered: $${report.totalWageredUsd.toFixed(2)}`);
console.log(`Paid out: $${report.totalPaidOutUsd.toFixed(2)}`);
console.log(`GGR: $${report.ggrUsd.toFixed(2)}`);
console.log(`Integrity: ${report.integrityHash}`);

// Per-game breakdown
for (const game of report.gameBreakdown) {
  console.log(`  ${game.gameName}: ${game.totalSpins} spins, net $${game.netPositionUsd.toFixed(2)}`);
}

Acknowledging a Report

When your records match the KINGSTONE report, acknowledge it:

const acknowledged = await client.acknowledgeSettlement('2026-03-23');
console.log(`Status: ${acknowledged.reportStatus}`); // "ACKNOWLEDGED"

Only reports with status GENERATED or PENDING can be acknowledged. If the report has already been acknowledged or disputed, the API returns error KS-4301 (409 Conflict).

Disputing a Report

If you find a discrepancy, dispute the report with a reason:

const disputed = await client.disputeSettlement(
  '2026-03-23',
  'Spin count mismatch: we recorded 1,204 spins, report shows 1,200',
);
console.log(`Status: ${disputed.reportStatus}`); // "DISPUTED"

Disputes are reviewed by the Predigy operations team. You will be contacted to resolve the discrepancy.

Reconciliation Workflow

Here is the recommended daily reconciliation process:

// 1. Fetch yesterday's report
const yesterday = new Date();
yesterday.setDate(yesterday.getDate() - 1);
const dateStr = yesterday.toISOString().split('T')[0];

const report = await client.getSettlement(dateStr);

// 2. Query your own database for the same date
const ourSpins = await yourDb.spins.count({ date: dateStr });
const ourWagered = await yourDb.spins.sumWagered({ date: dateStr });
const ourPaid = await yourDb.spins.sumPaid({ date: dateStr });

// 3. Compare
const spinsMatch = ourSpins === report.totalSpins;
const wageredMatch = Math.abs(ourWagered - report.totalWageredUsd) < 0.01;
const paidMatch = Math.abs(ourPaid - report.totalPaidOutUsd) < 0.01;

// 4. Acknowledge or dispute
if (spinsMatch && wageredMatch && paidMatch) {
  await client.acknowledgeSettlement(dateStr);
  console.log('Settlement acknowledged — numbers match.');
} else {
  const reason = `Mismatch: spins ${ourSpins} vs ${report.totalSpins}, ` +
    `wagered $${ourWagered} vs $${report.totalWageredUsd}`;
  await client.disputeSettlement(dateStr, reason);
  console.log('Settlement disputed — review required.');
}

Integrity Verification

Each report includes a SHA-256 integrityHash computed from the report data. You can use this hash to verify that a report has not been tampered with after generation. Store the hash when you first retrieve the report, and compare it on subsequent fetches.

Next Steps

• Set up webhooks to receive settlement.report_ready notifications
• Review compliance and RTP tracking