What this module is for

Use Actions / Merchant Balance to monitor the calculated operating balance used by automatic-withdrawal risk checks and to record manual CREDIT or DEBIT adjustments.

This is an operational control, not an accounting ledger or reconciliation report.

This module is intentionally narrow. The current CRM only exposes:

• a List page with the transaction journal and date filters
• a Form page for creating a new manual transaction

There is no edit, delete, or detail workflow in the current CRM surface.

Main surfaces

• List: journal of recorded merchant-balance transactions plus the current merchant-balance total
• Form: create-only workflow for one manual debit or credit adjustment

CREDIT and DEBIT

• CREDIT normally increases the merchant balance.
• DEBIT normally decreases the merchant balance.

The create form does not enforce a positive amount. A negative value reverses the normal direction, so use only positive amounts and select the intended transaction type.

How the current balance is calculated

The verified calculation is:

manual credits - manual debits - player wallet balances + successful deposits - withdrawals in statuses 0, 1, or 5

Wallet balances use the current currency exchange-rate row. Banking transactions use their stored conversion rate. Any required amount or rate that is missing, non-positive, or non-finite causes the calculation to fail instead of silently becoming zero.

The result is rounded half-up to two decimal places. The UI does not show a reporting currency, exchange-rate source, or rate timestamp, so do not present the displayed number as an audited currency total.

Effect on automatic withdrawals

The automatic-withdrawal services use a minimum merchant balance of 1000.

• batch processing stops when the current numeric merchant-balance value is below the threshold
• the batch guard subtracts each pending withdrawal's raw numeric amount before comparing the remainder with 1000
• the existing-withdrawal processor rejects processing when the current numeric balance is below the threshold

This threshold is implemented in the withdrawal services; it is not editable from the Merchant Balance screen.

The pending-withdrawal source returns amount and currency separately, and the batch guard does not convert the amount before this comparison. Treat 1000 as a raw numeric implementation guard, not as a proven same-currency reserve.

How to create an adjustment

1. Open Create.
2. Select CREDIT to increase or DEBIT to decrease the normal balance direction.
3. Enter a positive amount.
4. Review the current Merchant balance shown on the form.
5. Submit once.
6. Return to the journal and confirm the new row and refreshed current balance.

The current submit flow has no idempotency key or reliable visible in-flight lock. Check the journal before retrying a request.

Access recommendation

The module uses MerchantBalance: R for viewing and MerchantBalance: C for creation. Limit create access to finance, payments operations, or designated superadmins. Every manual adjustment should have an agreed business reason and an identifiable responsible operator.

Troubleshooting

If the balance looks wrong, check manual CREDIT/DEBIT rows, player wallet balances, successful deposits, included withdrawal statuses, stored exchange/conversion rates, and invalid numeric data.

Date filters change only the journal rows. They do not recalculate the current Merchant balance for the selected period.

Important caveats

• The table filters affect the transaction journal, but the large Merchant balance summary is calculated separately and is not restricted by the selected date range.
• Journal rows are append-only from this CRM surface. Operators can create a new adjustment, but this module has no edit or delete action for an older row.
• The create form snapshots superAdminUserId when its local state is initialized. If admin details are not available at that moment, the disabled field remains -1; the page does not re-synchronize it later.
• Amounts and the large summary are rendered as plain numbers without a currency code or symbol. The formula normalizes source amounts with stored rates, but this flow does not define the reporting currency, rate source ownership, or rate timestamp. Do not present the number as a proven currency total.
• The current-balance read fails instead of substituting zero when an amount is non-finite or a required rate is missing or non-positive.
• The automatic-withdrawal batch subtracts raw pending-withdrawal amounts without a verified currency conversion in that guard. Its 1000 threshold is therefore not proof of a same-currency reserve.
• The create flow does not enforce a positive amount. For a non-negative amount, DEBIT reduces and CREDIT increases the total; a negative amount reverses that normal direction.
• Submit has no idempotency key or visible in-flight lock. Verify the journal before repeating a submission.

The journal read flow, create flow, permission gates, and current-balance formula have been traced. Treat the top summary as a separate current-balance calculation, not as a total of the visible journal rows.