Payments Area
Access prerequisites
- Permission (module):
managePaymentLinkConfig(configure fee and split),reviewPaymentKyc(KYC queue),viewPaymentLinks(list of charges) — each tab requires its own module. - License/Feature:
PAYMENT_LINKSenabled on the tenant's license. - Menu container: GENERAL → Financial group
What it is / when to use
The Payments Area is where the operator manages merchants' PIX → USDT charge links. A merchant (an approved Midas-Web user) generates charge links that third parties pay via PIX; the net amount lands converted into USDT in the merchant's internal balance, minus a configurable fee that is the house revenue.
Here the operator does three things: configures each merchant (fee, enablement, display name and receiving PIX key), defines the fee split (how the revenue is split between the house operational cost and partners) and reviews the payers' KYC queue (document + selfie). There is also the list of charges for auditing and support.
Prerequisites
- Permission: the module corresponding to the tab registered for the operator's role (dual permission — CPM enum in the backend + dynamic module in the DB; without the module in the DB the tab/action does not appear, even with the correct enum).
- License/Feature:
PAYMENT_LINKSenabled on the tenant's license (Vault). If disabled, the Payments Area does not even appear in the menu. - Dependencies on other screens: the merchant must exist and be
APPROVED. To generate links it depends onpaymentsEnabled = truein the configuration and on a defined fee (or split). Partners that benefit from the split must be platform users with a USDT balance.
Step by step
- Go to Financial → Payments Area.
- On the Merchant configuration tab, search for the merchant by
userId, adjust fee, enable payments, display name and PIX key, and save (the fee confirmation requires step-up). - On the Fee split tab, build the distribution rows (house operational cost + partners) making sure the sum of the fractions equals the fee, and save (also with step-up).
- On the KYC queue tab, open each pending payer, check document and selfie side by side and approve or reject.
- On the List of charges tab, filter by merchant/status/period to audit charges and their payouts.
Fields
Merchant configuration (merchant_payment_config)
| Field | What it is | Required? | System/backend effect |
|---|---|---|---|
Merchant (merchantUserId) | Target Midas-Web user of the configuration | Yes | Key (merchant_user_id) of merchant_payment_config in the PaymentManagementService (PGH). It is the internal user ID, not the email. |
Fee (feePct) | Total fee charged on the gross, as a fraction | Yes | Stores fee_pct (numeric fraction). 0.03 = 3%. It is the percentage deducted from the gross on conversion. Frozen on the creation of each charge (snapshot fee_pct_snapshot) — changing it here only affects new charges. If there is a split, it must equal the sum of the rows. |
Enable payments (paymentsEnabled) | Turns link generation on/off for the merchant | Yes | Stores payments_enabled (bool). Gate: with false the merchant does not see the Payments Area in Midas-Web nor creates links. |
Display name (displayName) | Merchant name shown to the payer on the public page | Yes | Stores display_name. Appears in the public SPA (pay.axiadigitalsolutions.com) so the payer can identify who they are paying. |
PIX key (pixKey) | The merchant's PIX key that receives the PIX in REAL mode | Conditional (REAL) | Stores pix_key. Used by the QRcode issuance (bms-lib createStaticQRCode) — the PIX lands in the merchant's account. In TEST mode the PIX is a stub and the key is not required. |
Fee split (payment_fee_distribution)
| Field | What it is | Required? | System/backend effect |
|---|---|---|---|
Scope (scope) | GLOBAL (default template) or MERCHANT (per merchant) | Yes | Stores scope. MERCHANT rows fully override the merchant's GLOBAL (they do not merge). Without MERCHANT rows, the GLOBAL ones apply. |
Merchant (merchantUserId) | The row's merchant, when scope is MERCHANT | Conditional | Stores merchant_user_id (null in GLOBAL). |
Type (beneficiaryType) | OPERATIONAL_COST (house retention) or PARTNER (partner) | Yes | Stores beneficiary_type. OPERATIONAL_COST is retained in BRL at the house; PARTNER is credited in USDT to the partner. |
Partner (beneficiaryUserId) | The beneficiary partner's userId | Conditional (PARTNER) | Stores beneficiary_user_id (null for operational cost). The partner must be a platform user with a USDT account_balance — the payout is resolved by the userId. |
Fraction of the gross (pctOfGross) | The row's share of the gross amount, as a fraction | Yes | Stores pct_of_gross (numeric fraction, e.g. 0.027). The sum of the active rows must equal the merchant's feePct. |
Active (active) | Turns the row on/off | Yes | Stores active. Inactive rows do not enter the split nor the sum. |
KYC queue (payment_payer_kyc)
| Column | What it shows | Data source |
|---|---|---|
| Name / Document | Name and CPF/CNPJ informed by the payer | full_name, document |
| Birth date / Email | The payer's birth date and email (receipt) | birth_date, email |
| Document / Selfie | Images sent for side-by-side review | document_file_key, selfie_file_key (Storage payment-kyc/<token>/) |
| Consent / IP / UA | LGPD trail: consent, IP, User-Agent and timestamp | lgpd_consent, ip, user_agent, consent_at |
| Review status | PENDING_REVIEW, APPROVED or REJECTED | review_status, reviewed_by, reviewed_at, rejection_reason |
List of charges (payment_requests)
| Filter/Column | What it shows | Data source |
|---|---|---|
| Merchant / Status | Merchant and charge state (Waiting, Paid, Converted etc.) | merchant_user_id, status |
| Amount / Gross / Net | Charged amount, gross received and net converted | amount, gross_amount, net_amount |
| Fee / USDT quote | Frozen fee and quote applied on conversion | fee_pct_snapshot, fee_amount, usdt_rate |
| Payer | Payer (masked), payment and conversion date | Linked KYC, paid_at, converted_at |
Actions and modals
- Save merchant configuration: sends
PUT /v1/admin/payment-requests/merchants/:userId/config. Changing the fee requires step-up (re-authentication password+MFA, headerX-Step-Up-Token). - Save split: sends
PUT /v1/admin/payment-requests/merchants/:userId/fee-split(or/fee-split/globalfor the default template). Requires step-up and the backend validates that the sum of the fractions equals the fee (Σ pctOfGross == feePct); a divergence is rejected. - Approve / Reject KYC: sends
PATCH /v1/admin/payment-requests/kyc/:id/review. On rejection inform the reason (rejectionReason). Use the inline actions on the row (not the 3-dot menu). - Audit charge: opening a charge from the list shows the detail and the payouts journal; it is read/support, with no financial action.
Business rules / cautions
Attention
- The fee is a fraction, not a percentage.
0.03means 3%. Typing3would charge 300%. The same goes for eachpctOfGrossof the split. - The split sum must match the fee. If the fractions of the active rows do not add up exactly to the
feePct, the save is rejected. - The fee and the split are frozen on the creation of each charge (snapshot). Changing the configuration afterwards does not affect already-open charges — only the new ones.
- MERCHANT scope fully overrides GLOBAL. If you create a MERCHANT row, configure all the rows for that merchant (operational cost + partners); the GLOBAL template no longer applies to them.
- Partners must be users with a USDT balance. In TEST mode the payout is a USDT credit in the ledger; in REAL mode partners receive in BRL in the internal accounts and the merchant receives USDT.
KYC is capture-and-proceed
The payer's KYC review is post-payment: upon sending document and selfie, the payer already sees the PIX and pays. Rejecting the KYC in the queue does NOT undo an already-completed payment nor reverse the conversion — it is a compliance/audit decision. The effect of a rejection (blocking the merchant, opening an investigation) is an operational process, not automatic.
- Financial values: handled as BigNumber throughout the calculation (gross, fee, net, USDT) — no rounding; check the decimal places.
- Reconciliation by amount: the charge is only finalized if the received PIX amount matches exactly the charge amount (anti-collision of identifier). Underpayment/overpayment does not reconcile.
- Idempotency: marking as paid, the conversion order, the merchant credit, each split credit and the BLS usage use stable keys per transaction. Reprocessing is safe — FinLib returns
E00021("already processed"), which is success, not error.
Examples
Scenario 1 — Merchant with a 3% fee and a split of 0.30% house + 2.70% partners
The operator searches for merchant u-5678, sets fee 0.03, enables payments and registers display name and PIX key. On the Split tab, it creates 4 MERCHANT rows: OPERATIONAL_COST with pctOfGross 0.003 (house retention, BRL) and three PARTNER with 0.009 each (partners, USDT) — sum 0.03, equal to the fee. On a paid R$ 100 charge, the merchant receives ~R$ 97 in USDT, the partners receive the equivalent of R$ 2.70 in USDT and R$ 0.30 is retained in BRL at the house.
Scenario 2 — Review a payer's KYC
In the queue, the operator opens a PENDING_REVIEW payer, checks the document against the selfie and the data (name/CPF/birth date). If consistent, clicks Approve — the record becomes APPROVED. If there is an inconsistency (illegible photo, divergent data), clicks Reject with a reason; the status becomes REJECTED, but the already-made payment remains — the rejection becomes a compliance input.
Scenario 3 — Merchant without a split (fee only)
The operator sets only the fee 0.03 and enables the merchant, without registering split rows. The entire fee becomes house retention (OPERATIONAL_COST) — useful when there are no partners registered yet. Afterwards it is possible to add the MERCHANT rows; already-created charges keep the old snapshot (without split).