Mass Payment

Access Prerequisites

• Permission (module): executeMassPayment (required to create, approve, and cancel; without it, the screen is read-only)
• License/Feature: None specific.
• Menu container: GENERAL → Investments / Financial Distributions group

What it is / when to use

Mass Payment allows the administrator to execute token transfers in batch from a pre-configured list — eliminating repeated manual interventions. Each batch has a title, a list of items (destination wallet, amount, token) and goes through a lifecycle with mandatory approval and asynchronous execution by a scheduler.

Use it to pay many recipients at once: yields, transfers, campaigns, token payroll, etc. Recipients can be registered users or external wallets (without user_id).

The lifecycle is: creation (draft) → approval (releases execution) → execution (scheduler pays item by item, every 5 min) → finished (when all items have been paid).

Prerequisites

• Permission: executeMassPayment (dual — CPM enum in the backend + module in the DB). The Create (in the list) and Approve (in the detail) buttons only appear with it.
• Step-up / MFA: both creation and approval/cancellation require an MFA code (additional authentication). Without the code, the operation is not submitted.
• Dependencies: the tokens used must be registered (the screen validates each item against the token list and the wallet network).

Step by step

1. Go to Investments → Mass Payment (route /mass-payment).
2. Click Create to open the modal.
3. Choose the method: Manual (fill in item by item) or Upload (CSV with columns wallet, amount, token).
4. Enter the batch title and review the items (wallet, amount, token). The system validates each item.
5. Confirm — the MFA code will be requested. The batch is saved in waiting_approval, with all items in waiting_processment. Nothing is paid yet.
6. Open the batch details and click Approve (requires confirmation + MFA again). The status becomes approved and the batch enters the scheduler queue.
7. The scheduler runs every 5 minutes: pays the items, marks each one as paid (or failed, with retry in the next cycle). When all are paid, the batch becomes finished.

Fields (creation modal)

Field	Description	Required?	System/backend effect
Title	Name of the payment batch	Yes	title of mass_payment (up to 100 characters)
Method	Manual or Upload (CSV)	Yes	Defines how items are assembled; the CSV requires columns wallet, amount/value, token
Wallet (item)	Destination address	Yes	wallet of mass_payment_item; validated according to the token network (BTC/TRON/Solana/EVM); can be an external wallet
Amount (item)	Quantity to transfer	Yes	amount; must be > 0 (BigNumber)
Token (item)	Token/currency of the payment	Yes	unit_of_money; validated against the registered token list (tokenValid)
MFA Code	Additional authentication code	Yes	mfaCode sent to createMassPayment; without it creation does not proceed

Confirmation is only enabled when the title is filled in and all items have a valid token, amount > 0 and a valid wallet for the network.

Filters and columns (listing)

Filter / Column	What it shows	Data source
Search by title	Filters batches by title	title
Order	Newest / oldest	order (DESC/ASC)
Status	waiting_approval, approved, canceled, finished	status
Token	Filters by token (payment unit)	unitOfMoney
Date	Batch creation date	createdAt
Title (column)	Batch name	title
Status (column)	Current state; approved/finished in green, canceled in red	status

Actions and modals

• Create: opens the modal (Manual/Upload). Validates items and, upon MFA, calls createMassPayment. Saved in waiting_approval.
• Download sample CSV: generates a template with columns wallet, amount, token.
• View details: opens the batch with the item summary (total, pending, paid, failed, canceled) and the state of each item.
• Approve (in detail): available only in waiting_approval. Opens a confirmation alert and then requests MFA; calls updateMassPaymentStatus(..., APPROVED, mfaCode). Releases to the scheduler.
• Cancel (in detail): requests MFA and calls updateMassPaymentStatus(..., CANCELED, mfaCode). No payments are executed for a canceled batch.

Business rules / cautions

Attention

• Empty list is blocked — it is not possible to confirm a batch without items.
• An invalid CSV (missing columns, no rows) is rejected with an error message; fix the header (wallet, amount/value, token) and resubmit.
• The wallet is validated by the token network: BTC, TRON, Solana and EVM (Ethereum and compatible) have different validations. A wallet invalid for the network blocks confirmation.
• The batch does not become finished while there are pending items; failed items are reprocessed in the next scheduler cycle.

Irreversible

• Approval releases real payments to recipients. After approved, the scheduler executes transfers automatically — review the list before approving.
• MFA is required for creation, approval and cancellation (step-up): it is the security barrier against improper batch execution.

• Financial amounts: values are handled as BigNumber — without rounding; values ≤ 0 are rejected.
• Idempotency / retry: execution is per item; an item that fails is retried in the next cycle (every 5 min) without re-executing already paid ones. In FIN, repeated transfers protected by externalId return E00021 ("already processed"), which means success (already paid), not failure.
• External wallets: items can have only wallet (without user_id) — payment to an external/unregistered wallet is supported.

Examples

Scenario 1 — Manual disbursement to a few beneficiaries

You need to pay 5 partners in USDC. Click Create → Manual, add 5 items (EVM wallet + amount + USDC), give a title ("Partner disbursement - June"), confirm and enter the MFA. The batch is created in waiting_approval. Open the details, Approve (MFA again). Within 5 min the scheduler pays the items; when all become paid, the batch becomes finished.

Scenario 2 — Token payroll via CSV upload

To pay dozens of employees, download the sample CSV, fill in the columns wallet, amount, token and Upload it. The system previews the items and validates each wallet against the token network. Enter the title, confirm with MFA. Review in the detail and Approve. An item with an invalid wallet blocks confirmation — fix it before proceeding.

Scenario 3 — Payment to external wallet + failure handling

One of the recipients is an external wallet (no account on the platform): just enter the address, without user_id. After approving, if the transfer of an item fails (e.g.: transient network error), the item becomes failed and is reprocessed automatically in the next 5 min cycle; the other already-paid items are not re-executed. The batch only closes (finished) when all items are paid.

Related screens

• Distribution
• Loan Requests
• Financial