Panel — Operations & Intervention

This section does two jobs: monitoring (what happened) and intervention (what to do about stuck money). Interventions are not executed directly: one operator opens a request and another person approves it.

Monitoring

GET operations                      # filters: endUserId, walletAccountId, status, operationType
GET operations/:id
GET operations/:id/receipt
GET operations/:id/receipt.pdf
GET operations/export
GET topups/:id
GET withdrawals/:id
GET bill-payments
GET bill-payments/:id

What the operation fields mean: Operations.

Ops-health — stuck and pending money at a glance

GET ops-health

Permission: wallet:operation:read

The counters on a list screen only count the page currently fetched; ops-health answers the same question server-side, across the whole tenant. When the KPI on the operations screen and this endpoint disagree, this one is authoritative.

The response also carries generatedAt, postingStuckMinutes (default 5) and failedLookbackHours (24).

Four-eyes requests

Every intervention that touches money takes two steps:

1. Request. An operator requests the intervention. The request is stored permanently; the requester is taken from your session.
2. Approval. A person other than the requester approves it. Only then is the action executed.

The request body has no person field. If you add requesterPrincipal or approverPrincipal to the body, the request is rejected with 400. If the requester tries to approve their own request, it is rejected with 403 WALLET_FOUR_EYES_VIOLATION; the comparison uses the stored requester on the request record.

GET  intervention-requests                 # status, kind, targetId, limit, cursor
GET  intervention-requests/:id
POST intervention-requests/:id/approve     # { reason? }
POST intervention-requests/:id/reject      # { reason }

Request statuses:

If, after approval, a system failure prevents execution from completing, the request does not stay in APPROVED: it is picked up automatically within a few minutes. If the action was not applied, it is applied with the approver's record; if it was, the request closes as EXECUTED. If it cannot be proven that this request applied the action, the request becomes FAILED with failureCode: WALLET_INTERVENTION_OUTCOME_UNVERIFIED — check the record's history and open a new request if needed.

In the panel, the approval queue is the Four-Eyes Approvals screen (Dört-Göz Onayları) in the wallet operations menu. On a request you opened, the Approve button is disabled and the reason is shown.

Suspense funds

Money that arrives but cannot be attributed goes to suspense.

GET  suspense-funds                       # filter by status
POST suspense-funds/:id/match-requests    # { instructionId, reason } — four-eyes request
POST suspense-funds/:id/return            # { reason }

Operation and withdrawal interventions

Open a request to finalize a stuck or held operation. A withdrawal is an operation; both endpoints create the same request type (OPERATION).

POST operations/:id/intervention-requests
POST withdrawals/:id/intervention-requests

How a reversal (force_reverse) proceeds

A reversal starts by moving the operation to REVERSING before any money moves. A concurrent action that loses this claim (for example a bank result arriving at the same moment, or another intervention) never reaches the ledger; the money is reversed only once.

Held cash-out codes

POST cash-out/:id/hold-requests           # { action, reason }

Opens a request for a cash-out code stuck in risk review (HELD). The action set is different:

Top-up refunds

POST topups/:id/refund-requests           # { reason }

Opens a request to refund a completed card top-up; the refund is executed at approval.

Commission

GET business-accounts/:id/commission
PUT business-accounts/:id/commission

Commission configuration for a business account. Schedule versioning: Panel — Limit & Fee Schemes.

Intervention discipline

1. Read before you touch. The operation history (status transitions) answers nearly every question.
2. Write a reason. The reason field is the audit record and the only later answer to "why was this done".
3. Wait when uncertain. AWAITING_RECON is a waiting state, not a decision.
4. Read the request before approving. The requester and the approver are taken from their sessions and cannot be the same person; the value of the second pair of eyes lies in the approver actually reviewing the request.