Skip to content

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:

FieldDescription
reportDateThe date this report covers (YYYY-MM-DD)
totalSpinsTotal number of spins across all games
totalWageredUsdTotal amount wagered in USD
totalPaidOutUsdTotal amount paid out in USD
netPositionUsdNet position (wagered minus paid out)
ggrUsdGross Gaming Revenue in USD
gameBreakdownPer-game breakdown with individual totals
integrityHashSHA-256 hash of the report data for tamper detection
reportStatusCurrent status: PENDING, GENERATED, ACKNOWLEDGED, or DISPUTED

Listing Settlement Reports ​

Fetch your most recent reports with pagination:

typescript
import { KingstoneClient } from '@kingstoneapp/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:

typescript
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:

typescript
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 (any status other than GENERATED/PENDING), the API returns KS-4304 (409 Conflict).

Disputing a Report ​

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

typescript
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:

typescript
// 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 ​

KINGSTONE by Predigy Inc.