Polyflight balance operations

Required scopes: both polyflight:read and balance_operations:read.

GET /api/operator/polyflight/balance-operations
GET /api/operator/polyflight/balance-operations/{operationId}
GET /api/operator/polyflight/balance-operations/export
Authorization: Bearer {operator_api_key_or_staff_session}

operationId is a positive integer. Every route is constrained to the authenticated operator; a cross-operator ID returns 404 POLYFLIGHT_OPERATION_NOT_FOUND. Responses use Cache-Control: private, no-store.

List and export filters

The date interval is half-open. search does not inspect a ticket ID, request ID, remote reference, or evidence JSON.

curl -sS -G \
  -H "Authorization: Bearer ${OPERATOR_API_KEY}" \
  --data-urlencode "status=unknown,manual_review" \
  --data-urlencode "search=operator-user-123" \
  --data-urlencode "page_size=25" \
  "https://your-beacon-origin.example.com/api/operator/polyflight/balance-operations"

Representative list response

{
  "items": [
    {
      "operationId": 9102,
      "operatorId": 42,
      "operatorUserId": 701,
      "externalUserId": "operator-user-123",
      "purchaseRequestId": "018f70e4-df31-777d-b488-c5876162727e",
      "ticketId": "018f70e4-e9c3-7d86-a84c-7ead54e42953",
      "paymentObligationId": "018f7147-18d2-748e-ab27-4de495494087",
      "effect": "win_credit",
      "direction": "credit",
      "status": "manual_review",
      "amountMinor": "38000",
      "currencyCode": "IDR",
      "idempotencyKey": "mini_app_polyflight_ticket:018f70e4-e9c3-7d86-a84c-7ead54e42953:win",
      "remoteReference": null,
      "requestSentAt": "2026-08-17T12:00:04.000Z",
      "responseReceivedAt": null,
      "createdAt": "2026-08-17T12:00:03.500Z",
      "updatedAt": "2026-08-17T12:00:34.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25
}

Effects are purchase_debit, win_credit, loss_credit, refund_credit, and compensation_reversal. Directions are debit, credit, debit_reversal, or credit_reversal. A loss_credit operation has direction credit, amountMinor: "0", and key mini_app_polyflight_ticket:{ticketId}:loss; its linked obligation has effect loss. All other Polyflight effect amounts are positive.

The loss request uses reason mini_app_polyflight_loss, metadata.operation: "loss", and metadata.result: "lost"; newly planned win requests use metadata.result: "won". Both retain immutable ticket context and pinned transport without original-debit metadata. See Native wallet contract for the complete loss request/response.

Loss delivery is durable acknowledgement with an unchanged wallet balance, not money owed. Success produces no monetary accounting entries or clearing movement; an unresolved acknowledgement does not block flight financial settlement. paymentObligationId correlates with the new loss ticket.resolved.obligationId. The eight-event catalogue is unchanged, with no loss payout pending/processed callbacks. Historical losses are not backfilled, and already-planned/dispatched request evidence is never rewritten.

When no operations match, the list returns items: [] and total: 0. A page beyond the last match has empty items but retains the matching total.

Detail evidence

The detail response adds operator-safe immutable evidence:

{
  "operationId": 9102,
  "effect": "win_credit",
  "direction": "credit",
  "status": "manual_review",
  "amountMinor": "38000",
  "currencyCode": "IDR",
  "idempotencyKey": "mini_app_polyflight_ticket:018f70e4-e9c3-7d86-a84c-7ead54e42953:win",
  "evidence": {
    "originalOperationId": null,
    "requestJson": { "reason": "mini_app_polyflight_win" },
    "responseJson": null,
    "failureReason": "REMOTE_RESULT_UNKNOWN",
    "attemptCount": 1,
    "stateVersion": 3
  }
}

The actual response also retains every list field. Treat succeeded as confirmed wallet delivery; for loss_credit, this means the zero-amount result was acknowledged, not money paid. remoteReference is optional. failed means the recorded attempt did not apply. sent, unknown, and manual_review are unresolved; they do not prove success or non-application and must not be replayed under a new key. Zero-amount deliveries follow the same REST response, idempotency, ambiguity, and authenticated manual-resolution safety rules as other wallet effects. A final ticket result remains final while its credit is unresolved.

Operators can read evidence but cannot change operation state. Only an authorized Polynion administrator can record an audited confirmed_applied, confirmed_not_applied, or authorized same-key resume decision after receiving authoritative wallet evidence. Follow Operations, reconciliation, and rollback.

Export

Export applies the same filters to all matching rows. It returns CSV by default; add format=json for the canonical list envelope.

curl -sS -G \
  -H "Authorization: Bearer ${OPERATOR_API_KEY}" \
  --data-urlencode "status=unknown,manual_review" \
  "https://your-beacon-origin.example.com/api/operator/polyflight/balance-operations/export" \
  --output unresolved-polyflight-operations.csv

In the dashboard, open Polyflight → Wallet operations, select Details to inspect request/response evidence, and use Export all filtered for a reconciliation file.

Playground: /api-playground/polyflight?request=polyflight-balance-operations.