Operator guideEN

Merchant Balance / Form

Create-only form for posting a manual debit or credit transaction into the merchant-balance journal.

How to use this guide

Start with the main guide

Follow the explanation and examples first. Extra definitions and formulas are available below when you need them.

What this form does

Use this form to create one manual merchant-balance transaction. The transaction is stored as a journal row and then contributes to the current Merchant balance total according to its type.

How to use it

  • Review the current Merchant balance shown above the form. This is the all-time current merchant-balance total, not a form-local preview, and the page renders it without a currency code or symbol.
  • Confirm User ID is the current admin user ID. If it shows -1, do not submit; reload the page or contact an administrator because the admin details did not populate the disabled field correctly.
  • Choose DEBIT or CREDIT. With a non-negative amount, DEBIT decreases and CREDIT increases the merchant-balance formula. A negative amount reverses that direction, so do not submit one unless that signed adjustment is explicitly intended.
  • Enter the transaction Amount. The form starts at 0; replace it with the intended adjustment amount before submitting.
  • Click Submit once to create the journal entry. A success message is shown, the page requests its current merchant-balance data again, and then returns to the list after a short delay.

Important caveats

  • This is a create-only screen. It does not edit an existing transaction.
  • The User ID field is displayed but disabled. It snapshots superAdminUserId during local-state initialization and does not re-synchronize when admin details arrive later; the fallback is -1.
  • Save requires type, amount, and userId to be present and restricts type to DEBIT or CREDIT, but it has no explicit positive-amount or operator-friendly range rule.
  • The page does not show a separate confirmation step before submitting the adjustment.
  • The Submit button is not visibly locked while the request is in flight in the verified page code, so avoid repeated clicks.
  • After a successful create call, the page redirects back to the list page.
  • The same current merchant-balance total is shown here, and it is not scoped by any date filter.
  • The page has no idempotency key. Verify the journal before retrying after an uncertain response because repeated submissions can create repeated rows.
  • The transaction payload contains no currency field. Do not infer a verified transaction currency from this form or its unlabelled amounts.
More details

Definitions and formulas

Open only the section you need. The relevant section opens automatically when you request help for a specific item on screen.

Calculations6 topicsOpen details

Form initial state

The create form starts as a local draft with `DEBIT`, amount `0`, and the current admin user ID when admin details are available.

Formula
draft.type = DEBIT; draft.amount = 0; draft.userId = current admin superAdminUserId, or -1 when admin details are unavailable at form initialization time.
Caveats
The verified page initializes the draft once; it does not re-sync `User ID` after admin details load later., Because the field is disabled, an operator cannot correct `-1` from the form.

Type effect

The selected type determines how the manual transaction contributes to the current merchant-balance total after it is created.

Formula
manual contribution = amount when type is CREDIT; manual contribution = -amount when type is DEBIT.
Caveats
For a non-negative amount, DEBIT reduces and CREDIT increases the total., A negative amount reverses that normal direction.
Shared Formula Ref
../calculations.yaml#merchant_balance_total

Amount input normalization

The amount field can temporarily hold text while the operator types, but the verified blur handler converts an empty value to zero.

Formula
On change, the typed value is stored in the draft. On blur, an empty amount becomes 0; any other value is converted with Number(...).
Caveats
Save validation checks presence, not a separate positive-amount rule in the verified create flow., Negative values are accepted by the traced create path and reverse the normal type direction in the total formula., The page displays no currency code or symbol for this input.

Create payload

Submit sends the current local draft as the new manual merchant-balance transaction.

Formula
payload = { type: draft.type, amount: draft.amount, userId: draft.userId }.
Save Validation
`type` must be present., `amount` must be present., `userId` must be present.
Side Effects
A transaction row is created in the merchant-balance journal inside a save transaction., The create action is audit-tracked as a financial merchant-balance event., The page requests its current merchant-balance list and total again after a successful response.
Caveats
The payload has no currency field., The payload has no idempotency key; repeated successful submissions can create repeated rows.

Success redirect

After create success, the page waits briefly and returns to the merchant-balance list.

Formula
requestSuccess triggers delayed list navigation.
Caveats
The verified page does not show a separate post-create detail page.

Create validation boundaries

Save validation is minimal; this is not a guarded finance wizard.

Formula
Save requires type, amount, and userId to be present and restricts type to DEBIT or CREDIT. No explicit positive-amount, positive-user-ID, currency, or client-side idempotency rule was found in this flow.
Fields9 topicsOpen details

Create Merchant Balance Transaction

Identifies the create-only transaction screen.

Visual Type
page-heading

Success alert

Confirms the transaction was created and appears before the page returns to the list.

Visual Type
alert
Caveats
The verified page redirects back to the list after a short delay when this state is set.

Error alert

Shows the request error returned by the create flow.

Visual Type
alert

No permission

Replaces the form when the operator does not have Merchant Balance create permission.

Visual Type
empty-state

User ID

Current admin user ID written into the new transaction row.

Visual Type
disabled-number-input
Default Value
current admin `superAdminUserId`, or `-1` if admin details are unavailable when the form initializes.
Editability
disabled
Caveats
The verified page initializes this value once from admin details., If the field shows `-1`, the operator should not submit because the disabled field cannot be corrected on the page., The service checks presence, but no explicit positive-user-ID rule was found in this create service.

Type

Chooses whether the new manual transaction is saved as `DEBIT` or `CREDIT`.

Visual Type
select
Default Value
DEBIT
Allowed Values
DEBIT, CREDIT
Calculation Effect
The signed contribution is `-amount` for DEBIT and `amount` for CREDIT., For a non-negative amount, DEBIT reduces and CREDIT increases the total., A negative amount reverses that normal direction.

Amount

Amount of the manual adjustment that will be stored in the journal row.

Visual Type
numeric-input
Default Value
0
Caveats
The page temporarily allows an empty value while the operator is typing, then converts it to `0` on blur., Save validation verifies presence, but the verified create flow does not add a separate positive-amount rule in this flow., Negative values are accepted by the traced create path and reverse the normal DEBIT/CREDIT direction in the total formula., The UI does not show a currency code or symbol.

Submit

Sends the current `type`, `amount`, and `userId` as a new merchant-balance transaction.

Visual Type
primary-button
Caveats
The verified button has no separate confirmation dialog., The verified page does not show a dedicated in-flight disabled state for this button.

Cancel

Leaves the form and returns to the merchant-balance list without creating a transaction.

Visual Type
secondary-button
Metrics1 topicOpen details

Merchant balance

Current all-time balance shown for orientation before create; it is not a preview that includes the unsaved adjustment.

Aliases
current merchant balance on create form, merchant balance before adjustment
Formula
Manual rows with CREDIT contributing amount and DEBIT contributing negative amount, minus wallets divided by stored currency exchange rates, plus successful deposits divided by their banking conversion rates, minus withdrawals in statuses 0, 1, or 5 divided by their banking conversion rates.
Filter Dependencies
Form Draft: ignored by this metric | Date Range: no date range exists on the form and the metric is all-time
Timezone Basis
The service sets the database session to UTC, but the total query is not date-scoped.
Currency Basis
Not defined by the verified flow; neither the summary nor Amount input has a rendered currency code or symbol.
Exchange Rate Basis
Uses stored currencies.exchange_rate and per-transaction conversion_rate values selected by the SQL; rate ownership and timestamps are not exposed here.
Rounding Rule
Decimal ROUND_HALF_UP to two places, returned as a fixed two-decimal string.
Missing Rate Behavior
Missing or non-positive required rates fail the read; no zero substitution is used.
Refund Reversal Handling
Not separately identified; inclusion is controlled by the SQL transaction status predicates.
Display Rule
Raw fixed-decimal text shown only for a truthy result; green above zero and red otherwise.
Caveats
Submitting does not calculate an on-page after-adjustment preview., The payload and unlabelled display do not prove a transaction or reporting currency.
More help

Related pages

Actions / Merchant Balance

Operator workspace for reviewing the merchant-balance transaction journal and creating manual debit or credit adjustments.

Merchant Balance / List

Transaction journal for manual merchant-balance entries, with date filtering, pagination, and a separate current-balance summary.

Affiliate Deals / Form

Create and edit form for affiliate deals, including PID, date window, commercial terms, and responsible person.

Affiliate Payment Settings / Form

Create and edit form for one affiliate payment-setting record, with visible PID targeting, minimum deposit threshold, and active-state control.

Auto Tags Manager / Create

Full rule-builder for a new automatic tagging rule, including priority, tag actions, coupon actions, KPI field selection, and draft impact estimation.

Automatic Withdrawal / Form

Create and edit form for one automatic-withdrawal rule, including thresholds, KYC, countries, methods, tags, and per-currency limits.