OpenPoly logo
Operator Api

Polyflight settlement reports

Read signed native-IDR statements, exports, liabilities, payments, and additive corrections.

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.

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 IDR minor units. Allocation remainders are signed numerator integers, not IDR amounts.

settlementNetMinor determines direction:

  • positive: operator_owes_polynion;
  • negative: polynion_owes_operator, with the absolute value in transferAmountMinor;
  • 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; verify hmac-sha256-v1 only with the key version and secure verification process provided during onboarding.

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.

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": [...] }.

In the dashboard, open Polyflight → Settlement reports. Details loads the statement, payments, and corrections; Download canonical statement uses the detail export. See Terms, statements, and settlement for reconciliation and signed positive/negative examples.

Playground: /api-playground/polyflight?request=polyflight-settlement-reports.

Polyflight terms

Read current, scheduled, and complete operator-safe Polyflight commercial terms history.

Session

Inspect the current operator API key or staff session context.

Copyright © 2026