Polyflight settlement reports
Polyflight settlement reports
Required scope: polyflight_settlements:read.
GET /api/operator/polyflight/settlement-reports
GET /api/operator/polyflight/settlement-reports/{id}
GET /api/operator/polyflight/settlement-reports/export
GET /api/operator/polyflight/settlement-reports/payments
GET /api/operator/polyflight/settlement-reports/{id}/payments
GET /api/operator/polyflight/settlement-reports/{id}/adjustments
GET /api/operator/polyflight/settlement-reports/{id}/export
Authorization: Bearer {operator_api_key_or_staff_session}
Statement IDs are UUIDs. Every route is constrained to the authenticated operator and returns Cache-Control: private, no-store. These routes are read-only: operators cannot finalize, record or reverse a payment, or add an adjustment.
List finalized statements
The list accepts only page and page_size. Defaults are 1 and 50; maximums are 100000 and 200. Statements are newest local month first.
Statements combine Classic and Pro under the same operator terms and fixed settlement timezone. There is no game, date, user, or status filter for signed statements.
curl -sS -G \
-H "Authorization: Bearer ${OPERATOR_API_KEY}" \
--data-urlencode "page=1" \
--data-urlencode "page_size=25" \
"https://your-beacon-origin.example.com/api/operator/polyflight/settlement-reports"
The list contains finalized statements only. Before the first eligible month is finalized, the valid response is:
{ "items": [], "total": 0, "page": 1, "pageSize": 25 }
Representative statement
Each list item and the detail response use the same statement shape. The identifiers, digests, and signature below are illustrative, not a cryptographic verification test vector:
{
"id": "018f9f46-f07e-7dba-bb39-aa42a17a1f21",
"revisionIdentity": "018f9f46-f27c-78ad-b0e5-32de8eff21c5",
"operatorId": 42,
"month": "2026-08",
"timezone": "Asia/Jakarta",
"periodStartAt": "2026-07-31T17:00:00.000Z",
"periodEndAt": "2026-08-31T17:00:00.000Z",
"completed": true,
"blockers": [],
"inputEventIds": ["018f7147-acde-73bb-9ad2-c5b185e68c12"],
"inputEventDigest": "b624993746d9467c5f49c15179d26cb7b61cfb354c3554f243002ded5b67ce91",
"inputMaxRecordedAt": "2026-08-17T12:00:34.000Z",
"fee": {
"baseMinor": "500",
"operatorNumerator": "5000000",
"openingRemainderNumerator": 0,
"operatorAllocatedMinor": "500",
"polynionAllocatedMinor": "0",
"closingRemainderNumerator": 0
},
"position": {
"baseMinor": "9500",
"operatorNumerator": "76000000",
"openingRemainderNumerator": 0,
"operatorAllocatedMinor": "7600",
"polynionAllocatedMinor": "1900",
"closingRemainderNumerator": 0
},
"cashClearing": {
"receiptsMinor": "10000",
"outflowsMinor": "0",
"netMinor": "10000"
},
"operatorEntitlementMinor": "8100",
"polynionEntitlementMinor": "1900",
"openingLiabilities": {
"unadmittedSuspenseMinor": "0",
"openStakeMinor": "0",
"compensationMinor": "0",
"winningsMinor": "0",
"refundsMinor": "0"
},
"closingLiabilities": {
"unadmittedSuspenseMinor": "0",
"openStakeMinor": "0",
"compensationMinor": "0",
"winningsMinor": "0",
"refundsMinor": "0"
},
"priorBalanceDueMinor": "0",
"paymentsAppliedMinor": "0",
"adjustmentsAppliedMinor": "0",
"settlementNetMinor": "1900",
"transferDirection": "operator_owes_polynion",
"transferAmountMinor": "1900",
"termsBreakdown": [
{
"termsVersionId": "018f4f92-acde-79e3-9a11-26e38cb73582",
"ticketFeeShareBps": 10000,
"positionShareBps": 8000,
"feeBaseMinor": "500",
"feeOperatorNumerator": "5000000",
"positionBaseMinor": "9500",
"positionOperatorNumerator": "76000000"
}
],
"daily": [
{
"date": "2026-08-17",
"feeBaseMinor": "500",
"feeOperatorAllocatedMinor": "500",
"feePolynionAllocatedMinor": "0",
"positionBaseMinor": "9500",
"positionOperatorAllocatedMinor": "7600",
"positionPolynionAllocatedMinor": "1900"
}
],
"resultProcessingWatermark": {
"periodStartAt": "2026-07-31T17:00:00.000Z",
"periodEndAt": "2026-08-31T17:00:00.000Z",
"unknownCashCount": 0,
"unprocessedResultCount": 0,
"maxRevealedAt": "2026-08-17T12:00:03.000Z",
"maxVoidedAt": null
},
"statementDigest": "4f6a950bd50b87bc99a90816e01b4ed455ce3492827ae667c54a49101b085572",
"signatureVersion": "hmac-sha256-v1",
"signerKeyVersion": "polyflight-statements-2026-01",
"signature": "f06b85b09258931eec259b37bca6f429f02c06d74e7aab1a9fb4ebff438b6f94",
"finalizedByAdminId": 17,
"finalizationReason": "August close",
"finalizedAt": "2026-09-01T02:15:00.000Z"
}
Aggregate money values are decimal strings in whole-rupiah IDR minor units. Allocation remainders are signed numerator integers, not IDR amounts. Section allocation is rounded after summing all captured terms-version numerators, not separately per ticket or revision.
settlementNetMinor determines direction:
- positive:
operator_owes_polynion; - negative:
polynion_owes_operator, with the absolute value intransferAmountMinor; - zero:
settled.
It includes the previous statement balance, current Polynion fee and signed-position entitlement, recorded payments, and audited adjustments. It does not add cashClearing as income. Winnings, refunds, compensation, open stakes, and unadmitted suspense remain separate liabilities.
Retain revisionIdentity, input-event digest/watermark, statementDigest, signatureVersion, signerKeyVersion, and signature together. The API has no signer-key endpoint; request Polynion's approved verification process if independent hmac-sha256-v1 verification is required. A download alone is not signature verification.
Payments
GET /settlement-reports/payments returns { "items": [...] } for all operator payment history. GET /settlement-reports/{id}/payments returns { "statementId": "{id}", "items": [...] }.
{
"id": "018fa132-5310-72b0-844a-2fd99569312a",
"operatorId": 42,
"statementId": "018f9f46-f07e-7dba-bb39-aa42a17a1f21",
"kind": "payment",
"direction": "operator_to_polynion",
"currencyCode": "IDR",
"amountMinor": "1000",
"transferredAt": "2026-09-03T03:00:00.000Z",
"reference": "BANK-20260903-001",
"evidenceReference": "settlement-drive/2026-09/BANK-20260903-001",
"evidence": null,
"idempotencyKey": "statement-payment:42:2026-09-03:001",
"correctsPaymentId": null,
"recordedByAdminId": 17,
"reason": "Partial settlement",
"recordedAt": "2026-09-03T03:05:00.000Z"
}
kind is payment or payment_correction; direction is operator_to_polynion or polynion_to_operator. Corrections are additive and reference the original through correctsPaymentId.
Payments enter the settlement formula by recordedAt period, not the bank's transferredAt or the referenced statement's month. A payment linked to a finalized statement appears in its payment history without rewriting its signed balance. Consequently, transferAmountMinor is the amount at finalization, not a live outstanding balance or proof of bank transfer.
Adjustments
GET /settlement-reports/{id}/adjustments returns corrections whose originalStatementId is the requested statement:
{
"statementId": "018f9f46-f07e-7dba-bb39-aa42a17a1f21",
"items": [
{
"id": "018fa210-37ab-781c-91ca-4d77c196ad75",
"operatorId": 42,
"originalStatementId": "018f9f46-f07e-7dba-bb39-aa42a17a1f21",
"appliedStatementId": null,
"kind": "late_event_correction",
"currencyCode": "IDR",
"amountMinor": "-500",
"effectiveAt": "2026-09-04T04:00:00.000Z",
"idempotencyKey": "statement-adjustment:42:2026-09-04:001",
"reversesAdjustmentId": null,
"reason": "Late cancellation correction",
"evidenceReference": "case/PF-20260817-1200-A",
"evidence": null,
"recordedByAdminId": 17,
"recordedAt": "2026-09-04T04:10:00.000Z"
}
]
}
kind is commercial_adjustment, late_event_correction, or adjustment_reversal. A null appliedStatementId is pending application to a later open statement; a non-null value identifies the later statement that absorbed it. The signed original statement never changes.
Download reports
The collection export returns every finalized operator statement; it has no date or status filters. The detail export returns the exact statement plus its payment history.
# All finalized statements as CSV
curl -sS \
-H "Authorization: Bearer ${OPERATOR_API_KEY}" \
"https://your-beacon-origin.example.com/api/operator/polyflight/settlement-reports/export" \
--output polyflight-settlement-reports.csv
# One canonical statement and its payments as JSON
curl -sS \
-H "Authorization: Bearer ${OPERATOR_API_KEY}" \
"https://your-beacon-origin.example.com/api/operator/polyflight/settlement-reports/018f9f46-f07e-7dba-bb39-aa42a17a1f21/export?format=json" \
--output polyflight-statement-2026-08.json
CSV is the default; add format=json for canonical JSON. Collection JSON is the normal list envelope. Detail JSON is { "statement": {...}, "payments": [...] }; adjustments must be fetched separately. CSV nests structured fields as JSON cells and protects spreadsheet-formula prefixes, including signed negative values. Use JSON and exact integer arithmetic for machine reconciliation rather than assuming every CSV amount cell is an unquoted integer.
In the dashboard, open Polyflight → Settlement reports. Details loads the statement, payments, and corrections; Download canonical statement uses the CSV detail export. Export all includes all finalized statements, not just the displayed page. These operator routes and this screen do not provide an invoice-PDF endpoint or payment-write action. See Terms, statements, and settlement for reconciliation and signed positive/negative examples.
Playground: /api-playground/polyflight?request=polyflight-settlement-reports.