Documentação

English

Português
Español

English

Português
Español

Appearance

User Charge Registration ​

Access prerequisites

  • Permission (module): processPaymentQueue
  • License/Feature: None specific.
  • Menu container: GENERAL → group Charges (route /manage-recurrences)

What it is / when to use ​

This screen creates monthly recurring charges that debit the user within a date window (start and end). It is the tool for monthly fees, subscriptions, administrative fees and any debit that needs to repeat over several months against a customer's balance.

Unlike Payroll (which pays the user on behalf of the company) and Automatic Charges (perpetual, by day of the month), this charge has a defined period: upon saving, the backend calculates how many months fit between the start date and the end date and schedules one installment per month. A job in the FinanceManagementService (FMS) iterates over these pending installments and applies them on the due date.

Prerequisites ​

  • Permission: processPaymentQueue registered for the operator role (dual permission — CPM enum in the backend + dynamic module in the DB; without the module in the DB the button does not appear, even with the correct enum).
  • License/Feature: None specific.
  • Dependencies on other screens: the target user must exist and be APPROVED — the charge debits their balance (crypto wallet or BRL digital account). The ID entered in the modal is the userIdTo (internal user identifier), not the email.

Step by step ​

  1. Go to Charges → User Charge Registration (route /manage-recurrences).
  2. The listing shows all charges already registered, in descending order of creation, with the email of the user resolved from userIdTo.
  3. Click Create new charge to open the registration modal.
  4. Fill in User ID, Description, Currency, Amount, Start date and End date (format dd/mm/yyyy).
  5. Confirm with Save. The backend records the charge and generates the monthly installments between the two dates.
  6. To remove a charge, use the trash icon on the row; to open the user, use the eye (visibility) icon, which navigates to the user details.

Fields (registration modal) ​

FieldWhat it isRequired?System/backend effect
User IDInternal identifier (userIdTo) of the customer to be debitedYesSaves user_id_to in recurrently_charges (FMS). This is the internal ID, not the email. Defines whose balance is debited each month.
DescriptionFree text that appears in the statement/transactionYesBecomes the transactionDescription of the wallet transaction or the BMS credit description. Max 250 characters in the form / 140 in the database.
CurrencyCurrency symbol for the charge (e.g. BRL, tBRL, token symbol)YesSaves unit_of_money_requested. Determines the payment rail: if BRL, the debit is made via digital account (BMS giveUserBalance against the main account); any other value is treated as a crypto wallet transaction to the walletForBonus.
AmountAmount to debit per installmentYes (> 0)Saves amount_requested. Treated as BigNumber during processing (no rounding). The same amount is replicated in each monthly installment.
Start dateFirst billing period (dd/mm/yyyy)YesSaves creation_date. This is the date of the first installment.
End dateLast billing period (dd/mm/yyyy)Yes (≥ start)Saves expiration_date. The backend calculates the number of months between start and end and creates one installment (recurrently_charges_payments) per month. If the interval is less than ~1 month, no additional monthly installments are generated.
How installments are generated

Upon saving, the FMS calculates the difference in days between start and end and converts it to months (days / 30). For each month, it creates an installment record with applied = false and the date for that month. The recurrence scheduler sweeps through pending installments and applies each one on its date, marking applied = true upon completion.

Actions and modals ​

  • Create new charge: opens the RecurrencyModalComponent modal. Validates that all fields are filled, amount > 0 and end date ≥ start date before enabling Save.
  • Save: sends to POST /v1/recurrently/create. On success, closes the modal and reloads the list.
  • Delete (trash): calls POST /v1/recurrently/delete with the recurrencyId. Removes the charge and the monthly installments not yet applied. After confirmation the page is reloaded.
  • View user (eye): navigates to the recipient's User Details.

Business rules / cautions ​

Attention

  • The User ID field is the internal identifier (userIdTo), not the email. Retrieve it from the User Details.
  • The Currency determines the rail: BRL debits via the digital account; any other symbol debits via the crypto wallet. Entering the wrong currency causes the debit to leave from the wrong place (or fail due to missing balance/route).
  • The number of installments depends exclusively on the start → end interval. Dates that are very close together may not generate any monthly installments.
  • Deleting a charge removes the pending installments, but does not reverse installments already applied.
  • Financial values: treated as BigNumber in the scheduler — no rounding; verify the decimal places for the currency/token.
  • Idempotency: each installment is applied with an externalId equal to the installment's id. If the service reprocesses after a crash, FinLib returns E00021 ("already processed") — this is success, not an error: the amount has already been debited and the installment is marked as applied.
  • APPROVED status: the target user must be approved for the debit (wallet or digital account) to be carried out.

Examples ​

Scenario 1 — 6-month subscription in BRL

The operator creates a charge for user u-1234, description "Pro Plan Monthly Fee", currency BRL, amount 49.90, start 01/06/2026 and end 01/12/2026. Upon saving, the FMS generates 6 monthly installments (June through December). Each month the scheduler debits R$ 49.90 from the user's digital account to the main account via BMS, and marks the installment as applied. In December, with the window closed, there are no more pending installments.

Scenario 2 — Administrative fee in utility token

Charge in currency UTK (utility token), amount 10, start 01/06/2026, end 01/09/2026. Because the currency is not BRL, each installment becomes a wallet transaction that moves 10 UTK from the user's wallet to the configured walletForBonus. There are 3 installments (June, July, August). Useful for discounting fees in token without touching the bank account.

Scenario 3 — Correction by deletion before the first debit

The operator notices they entered the wrong amount right after registering. Since no installment has been applied yet, they click the trash icon: the charge and all pending installments are removed. They then create the charge again with the correct amount. No debit was made in the interval.