# ARENA BATTLE — OPERATOR BILLING

## 1. Scope and calculation
Service invoices are separate from player wallets and commission payouts owed to operators. Issuing an invoice or recording payment does not change player balances. Pooled game losses are not automatically charged to the winning player's site.

Automation and email are disabled initially. Until commercial terms are agreed, use `manual`: finance staff enter service lines in a draft and then issue it. `fixed` uses an agreed monthly fee. `provider_share_v1` creates a draft from the provider's commission share on finalized room results in a closed month; manual review is required. Period competitions, game losses and player balances are excluded.

The model version, company details, tax rate, period summary and lines are stored with the invoice. New settings do not rewrite historical invoices. The PDF is a commercial service statement; it is not connected to a tax authority e-invoicing system. Enter verified legal company, tax and bank information.

## 2. Monthly workflow and panels
In the main admin, open Invoices > Billing settings to enter the issuer and payment instructions. Select an operator in the site filter, then open Site settings to set the recipient, email, language, amount, tax, invoice day and due days.

Invoice day is 1–28 and due days are 1–90. Periods are calendar months in Istanbul time. On or after the configured day, automation processes the previous closed month. Only one record is created per site and month. Unchanged, agreed fixed-fee drafts created by the scheduler can be issued automatically. Manual and commission-model drafts require staff review.

The lifecycle is draft > payment due > paid. Partial payments are supported. Issued lines are immutable. An invoice with no recorded payments can be voided with a reason; its record is retained and a second invoice for the month is not created. Correcting a paid document requires accounting review. The system does not debit bank accounts or perform automatic refunds.

Operator > Invoices shows only that site's documents, lines, period summaries, outstanding amounts, payment history and PDF downloads. Other sites' invoices are not visible. When the main admin records payment, the operator sees the updated status on the next refresh.

Panel language is saved per staff account, separately for admins and operators, and restored on subsequent sign-ins including other devices. It can be changed at any time. Authenticated `GET /control/api/preferences` and `GET /operator-api/preferences` return the current account preference. `PATCH` to the same endpoint accepts only `{"locale":"tr"}` or `{"locale":"en"}` and requires Origin and CSRF verification. No other account ID is accepted. A null locale means no account preference has been saved yet.

## 3. Panel API endpoints
These endpoints use panel session cookies, not operator integration API keys. Writes require the relevant panel Origin and `X-CSRF-Token`. Admin reads require `finance.read`; writes require `finance.manage`. Operator reads require `finance.read`.

```http Main admin
GET /control/api/billing?tenant=all
PATCH /control/api/billing/settings
PATCH /control/api/billing/sites/:tenantId
POST /control/api/billing/invoices
GET /control/api/billing/invoices/:invoiceId
PATCH /control/api/billing/invoices/:invoiceId
GET /control/api/billing/invoices/:invoiceId/pdf
POST /control/api/billing/invoices/:invoiceId/issue
POST /control/api/billing/invoices/:invoiceId/payments
POST /control/api/billing/invoices/:invoiceId/void
POST /control/api/billing/invoices/:invoiceId/email
```

```http Operator — own site only
GET /operator-api/billing
GET /operator-api/billing/invoices/:invoiceId
GET /operator-api/billing/invoices/:invoiceId/pdf
```

```json Create a draft
{"tenantId":"SITE_ID","period":"2026-09","reference":"monthly:2026-09"}
```

```json Record a partial payment — use a unique bank reference
{"amountMinor":250000,"reference":"bank-receipt-20261015-001","note":"Verified against the bank statement"}
```

List endpoints accept page (50 invoices per page); summary totals cover all matching periods. Amounts are integer TRY minor units. Retrying the same payment reference and content never records a second payment. Reusing a reference with different content is rejected. Overpayments are rejected. `issue` takes an empty JSON object. `void` requires a `reason` of at least 5 characters. PDF downloads require authentication; documents are not exposed through public links.

## 4. Email and PDF
Mail credentials belong only in protected server environment configuration. Never include them in client packages, operator API keys or browser code.

```text Server environment variables
BILLING_SMTP_HOST=smtp.example.com
BILLING_SMTP_PORT=587
BILLING_SMTP_USER=YOUR_SMTP_USER
BILLING_SMTP_PASSWORD=YOUR_SMTP_PASSWORD
BILLING_MAIL_FROM=Arena Battle <billing@example.com>
```

Use port 587 with STARTTLS or 465 with TLS. Certificate verification and TLS 1.2 minimum are required. Both global and per-site email switches must be enabled. Messages include invoice PDFs, payment notifications and optional due reminders. PDF downloads use the current admin/operator panel language (`?lang=tr` or `?lang=en`). Without this parameter the saved invoice language is used. Unsupported or repeated language parameters are rejected. This affects presentation only; invoice amounts and original records remain unchanged. Email and its PDF attachment retain the recipient language from the invoice settings. Custom descriptions and payment instructions remain as entered. The portal link in the email requires sign-in.

The delivery queue is durable. Due reminders are created for at most three weekly intervals. SMTP acceptance is not proof of delivery to the recipient's inbox. An ambiguous delivery is not retried automatically: staff must check the mailbox and SMTP logs before requesting a retry. When SMTP is not configured, the panel says so and no real mail is sent.

## 5. Default site risk rules
Operator > Risk and alerts starts with platform defaults. Operators can change their own thresholds or restore defaults. See the Risk and notifications guide for the rules and API details.

Shared IP/device, repeated opponents, large payouts, unusual win rates and rapid joining are review signals, not proof of fraud on their own. These signals never automatically deduct funds, void winnings or block players. Started games cannot be cancelled by risk rules.

## 6. Corporate inquiry staff
Corporate provider-site inquiries arrive in the main admin's Partnership inquiries page; no separate panel is needed. Under Team and roles, create a custom role containing only `inquiries.read` and, if needed, `inquiries.manage`. Assign it to the staff account. That account cannot view finance, players or site API keys.

## 7. Setup and acceptance
Verify issuer, bank details, recipient, contractual amount and tax rate first. With isolated test data, check drafts, PDFs, issuance, partial/full payments and site boundaries. Test actual email delivery with a verified test recipient before enabling automation. Back up the database with the existing encryption keys.

Player iframe and module wallet/API contracts are unchanged; billing alone does not require redeploying player files. The updated integration ZIP includes both languages of this guide. Future commercial models should use a new model version and new-period drafts; issued historical documents must not be recalculated retroactively.
