Documentação

English

Português
Español

English

Português
Español

Appearance

Create / Edit Contract ​

Access Prerequisites

  • Permission (module): manageContracts
  • License/Feature: None (for automatic debit in fiat: DIGITAL_BANKING)
  • Menu container: GENERAL → group Contracts (accessed from the Contract list)

What it is / when to use ​

Two-step stepper form to register a recurring billing contract with a customer: in the General step you define the title, description, payment type (fiat or token), total amount, validity period, attached document, customer, and contract type; in the Payments step the system automatically generates the monthly installments by dividing the total amount by the validity period, and allows you to adjust the date of each installment. Use this to formalize monthly fees, subscriptions, installment payment plans, and any recurring charge tied to a user.

Pre-conditions ​

  • Permission: manageContracts (the route and save buttons only exist with this module). Dual permission — CPM enum on the backend + dynamic module in the DB.
  • License/Feature: None required to create. For automatic fiat debit to work afterwards, DIGITAL_BANKING must be enabled.
  • Dependencies on other screens:
    • At least one Contract Type must be registered — see Contract Types.
    • For token payment, the billing token must exist in [Manage Tokens].
    • The customer's e-mail must belong to an existing user — the form validates this before allowing you to advance.

Step by step ​

  1. In the Contract list, click New (or the pencil icon to edit).
  2. General step: fill in the title, description, payment type, total amount, validity dates, attach the document, and enter the customer's e-mail.
  3. Click the validate if user exists link next to the e-mail — this is mandatory. A green checkmark confirms it; without it, advancing is blocked.
  4. Select the Contract Type (and the Billing Token, if payment is in token).
  5. Advance to Payments: review the automatically generated installments; adjust dates if necessary (edit mode).
  6. Click Save and confirm in the bottom-sheet.

Fields — General step ​

FieldWhat it isRequired?Effect on the system/backend
TitleContract nameYesSaves title. Immutable in edit mode (field disabled in edit).
DescriptionFree-text description of the agreement (up to 4000 characters)YesSaves description. Immutable in edit mode.
Payment typeFiat or TokenYes (default Fiat)Saves paymentType. Determines how the debit occurs: fiat debits the digital account; token debits the customer's wallet. Immutable in edit mode.
Billing tokenToken used when payment = tokenConditional (only if Token)Saves paymentTokenId. In fiat, the field is cleared automatically (paymentTokenId = '').
Total amountTotal contract amountYesSaves totalValue as BigNumber (currency/token mask). In fiat, formatted with 2 decimal places; in token, with the token's precision. Immutable in edit mode.
Start dateBeginning of the validity periodYesSaves initialDate. Cannot be in the past (datepicker filter blocks past dates).
End dateEnd of the validity periodYesSaves endDate. Together with the start date, defines the number of monthly installments. Immutable in edit mode.
DocumentContract file (PDF/image)YesUploaded via the files API; saves document.{name,url}. 10 MB limit and restricted types — invalid file shows an error.
Customer e-mailIdentifies the user to be billedYesValidated by getUserBasicInfo; only with the green checkmark (emailChecked) does the form unlock. Saves customerEmail. Immutable in edit mode.
Contract typeContract categoryYesSaves contractTypeId. Populated by Contract Types.

Fields — Payments step ​

FieldWhat it isRequired?Effect on the system/backend
Installment listMonthly installments generated automaticallySystem-generatedOn creation, the total is divided by (number of months between dates) + 1; each installment receives amount and competence (one per month). Initial status: pending.
Installment date (competence)When the installment is due / will be debitedEditable (pending installments)Editing opens the date modal; calls updateContractPayment. Only pending installments have the pencil icon.
Installment amountAmount of each installmentCalculatedtotalValue / (monthDiff + 1) (BigNumber). Displayed with the currency symbol (fiat) or token ID.
Installment statuspending / paid / overdue / cancelledSystemUpdated by the billing scheduler or by manual payment.

Actions and modals ​

  • Next / Back: stepper navigation. In creation mode the stepper is linear: the General step only unlocks advancement when all required fields are filled and the e-mail has been validated.
  • Validate user: validates the customer's e-mail; mandatory to proceed. The clear icon resets the validation.
  • Edit installment date: opens a date-selection modal; on confirmation, saves and reloads the screen.
  • Save: opens a confirmation bottom-sheet. On creation calls createContract; on edit calls updateContract. Success → returns to the list with a snackbar.

Business rules / considerations ​

Attention

  • In edit mode, most fields are read-only. Only the contract type and the dates of pending installments can be changed. Title, description, amount, payment type, token, validity dates, document, and customer are locked after creation. To change essential details, create a new contract.
  • E-mail validation is mandatory: without the green checkmark, advancement is blocked. An e-mail that does not correspond to an existing user prevents creation.
  • Installment generation: the number of installments is months_between_dates + 1. A validity from 01/Jan to 01/Jun generates 6 installments; define the dates with this in mind.
  • Past start date is blocked — it is not possible to register a contract with a retroactive start date via the datepicker.
  • Financial values: total and installments are BigNumber — no rounding. The division may produce repeating decimals; verify the decimal places according to fiat (2) or token (token precision).
  • Automatic debit & billing: once created and accepted by the customer, the daily scheduler (08:00) debits overdue installments. In fiat, it transfers from the customer's digital account to the main account (requires DIGITAL_BANKING); in token, it performs a wallet transaction. With insufficient balance, the installment becomes overdue and the customer/admin receive an e-mail.
  • Idempotency: the installment debit uses the installment id as externalId in the wallet transaction — reprocessing the same installment is safe and does not duplicate the debit.

Examples ​

Scenario 1 — Monthly fiat subscription with automatic debit (12 installments)
  1. General: Title "Annual Premium Plan", service description, Payment type = Fiat, Total amount = R$ 1,200.00, validity 01/07 to 01/06 of the following year (generates 12 installments of R$ 100.00).
  2. Attach the signed PDF, enter the customer's e-mail and click validate (green checkmark).
  3. Select the Contract type "Subscription".
  4. Payments: verify the 12 monthly installments of R$ 100.00, with competence on the 1st of each month.
  5. Save. In the List, enable Automatic debit.
  6. Result: after the customer accepts in the app, every 1st of the month (processed at 08:00) the system debits R$ 100.00 from the digital account. Insufficient balance → installment becomes overdue and notifications are sent.
Scenario 2 — Contract paid in token (wallet)
  1. General: Payment type = Token, choose the Billing token (e.g., USDT), Total amount = 600 (token precision), validity of 6 months → 6 installments of 100.
  2. Attach the document, validate the customer's e-mail, select the contract type.
  3. Payments: 6 installments of 100 USDT.
  4. Save and enable automatic debit.
  5. Result: the charge verifies the token balance in the customer's wallet and performs a wallet transaction (does not touch the digital account). Insufficient balance → installment becomes overdue.
Scenario 3 — Adjusting the date of a specific installment
  1. Open the contract in edit mode (or in Details).
  2. In the installment grid, locate a pending installment (only these have the pencil icon).
  3. Click edit, choose the new competence date, and confirm.
  4. Result: updateContractPayment saves the new competence; the screen reloads. Paid or overdue installments cannot have their date changed.