Área de Pagos
Requisitos previos de acceso
- Permiso (módulo):
managePaymentLinkConfig(configurar comisión y split),reviewPaymentKyc(cola de KYC),viewPaymentLinks(lista de cobros) — cada pestaña exige su módulo. - Licencia/Feature:
PAYMENT_LINKShabilitada en la licencia del tenant. - Contenedor del menú: GENERAL → grupo Financiero
Qué es / cuándo usar
El Área de Pagos es donde el operador administra los enlaces de cobro PIX → USDT de los comerciantes. Un comerciante (usuario Midas-Web aprobado) genera enlaces de cobro que terceros pagan vía PIX; el neto cae convertido en USDT en el saldo interno del comerciante, descontada una comisión configurable que es el ingreso de la casa.
Aquí el operador hace tres cosas: configura cada comerciante (comisión, habilitación, nombre de visualización y clave PIX de recepción), define el split de la comisión (cómo se reparte el ingreso entre el costo operativo de la casa y los socios) y revisa la cola de KYC de los pagadores (documento + selfie). Existe además la lista de cobros para auditoría y soporte.
Requisitos previos
- Permiso: el módulo correspondiente a la pestaña registrado para el rol del operador (permiso doble — enum CPM en el backend + módulo dinámico en la DB; sin el módulo en la DB la pestaña/acción no aparece, aun con el enum correcto).
- Licencia/Feature:
PAYMENT_LINKShabilitada en la licencia del tenant (Vault). Si está deshabilitada, el Área de Pagos ni siquiera aparece en el menú. - Dependencias de otras pantallas: el comerciante debe existir y estar
APPROVED. Para generar enlaces depende depaymentsEnabled = trueen la configuración y de una comisión (o split) definida. Los socios beneficiarios del split deben ser usuarios de la plataforma con saldo USDT.
Paso a paso
- Acceda a Financiero → Área de Pagos.
- En la pestaña Configuración del comerciante, busque al comerciante por
userId, ajuste comisión, habilitar pagos, nombre de visualización y clave PIX, y guarde (la confirmación de la comisión pide step-up). - En la pestaña Split de la comisión, arme las filas de distribución (costo operativo de la casa + socios) garantizando que la suma de las fracciones sea igual a la comisión, y guarde (también con step-up).
- En la pestaña Cola de KYC, abra cada pagador pendiente, verifique documento y selfie lado a lado y apruebe o rechace.
- En la pestaña Lista de cobros, filtre por comerciante/estado/período para auditar cobros y sus traspasos.
Campos
Configuración del comerciante (merchant_payment_config)
| Campo | Qué es | ¿Obligatorio? | Efecto en el sistema/backend |
|---|---|---|---|
Comerciante (merchantUserId) | Usuario Midas-Web objetivo de la configuración | Sí | Clave (merchant_user_id) de merchant_payment_config en el PaymentManagementService (PGH). Es el ID interno del usuario, no el correo. |
Comisión (feePct) | Comisión total cobrada sobre el bruto, en fracción | Sí | Graba fee_pct (numeric fracción). 0.03 = 3%. Es el porcentaje descontado del bruto en la conversión. Congelada en la creación de cada cobro (snapshot fee_pct_snapshot) — cambiarla aquí solo afecta cobros nuevos. Si hay split, debe ser igual a la suma de las filas. |
Habilitar pagos (paymentsEnabled) | Activa/desactiva la generación de enlaces para el comerciante | Sí | Graba payments_enabled (bool). Gate: con false el comerciante no ve el Área de Pagos en Midas-Web ni crea enlaces. |
Nombre de visualización (displayName) | Nombre del comerciante mostrado al pagador en la página pública | Sí | Graba display_name. Aparece en la SPA pública (pay.axiadigitalsolutions.com) para que el pagador identifique a quién está pagando. |
Clave PIX (pixKey) | Clave PIX del comerciante que recibe el PIX en modo REAL | Condicional (REAL) | Graba pix_key. Usada por la emisión del QRcode (bms-lib createStaticQRCode) — el PIX cae en la cuenta del comerciante. En modo TEST el PIX es stub y la clave no se exige. |
Split de la comisión (payment_fee_distribution)
| Campo | Qué es | ¿Obligatorio? | Efecto en el sistema/backend |
|---|---|---|---|
Alcance (scope) | GLOBAL (plantilla default) o MERCHANT (por comerciante) | Sí | Graba scope. Las filas MERCHANT sobreponen por completo el GLOBAL del comerciante (no se fusionan). Sin filas MERCHANT, valen las GLOBAL. |
Comerciante (merchantUserId) | Comerciante de la fila, cuando el alcance es MERCHANT | Condicional | Graba merchant_user_id (null en GLOBAL). |
Tipo (beneficiaryType) | OPERATIONAL_COST (retención de la casa) o PARTNER (socio) | Sí | Graba beneficiary_type. OPERATIONAL_COST queda retenido en BRL en la casa; PARTNER se acredita en USDT al socio. |
Socio (beneficiaryUserId) | userId del socio beneficiario | Condicional (PARTNER) | Graba beneficiary_user_id (null para costo operativo). El socio debe ser usuario de la plataforma con account_balance USDT — el traspaso se resuelve por el userId. |
Fracción sobre el bruto (pctOfGross) | Porción de la fila sobre el valor bruto, en fracción | Sí | Graba pct_of_gross (numeric fracción, ej. 0.027). La suma de las filas activas debe ser igual a la feePct del comerciante. |
Activa (active) | Activa/desactiva la fila | Sí | Graba active. Las filas inactivas no entran en el split ni en la suma. |
Cola de KYC (payment_payer_kyc)
| Columna | Qué muestra | Origen del dato |
|---|---|---|
| Nombre / Documento | Nombre y CPF/CNPJ informados por el pagador | full_name, document |
| Nacimiento / Correo | Fecha de nacimiento y correo del pagador (recibo) | birth_date, email |
| Documento / Selfie | Imágenes enviadas para revisión lado a lado | document_file_key, selfie_file_key (Storage payment-kyc/<token>/) |
| Consentimiento / IP / UA | Rastro LGPD: consentimiento, IP, User-Agent y timestamp | lgpd_consent, ip, user_agent, consent_at |
| Estado de revisión | PENDING_REVIEW, APPROVED o REJECTED | review_status, reviewed_by, reviewed_at, rejection_reason |
Lista de cobros (payment_requests)
| Filtro/Columna | Qué muestra | Origen del dato |
|---|---|---|
| Comerciante / Estado | Comerciante y estado del cobro (En espera, Pagado, Convertido etc.) | merchant_user_id, status |
| Valor / Bruto / Neto | Valor cobrado, bruto recibido y neto convertido | amount, gross_amount, net_amount |
| Comisión / Cotización USDT | Comisión congelada y cotización aplicada en la conversión | fee_pct_snapshot, fee_amount, usdt_rate |
| Pagador | Pagador (enmascarado), fecha de pago y conversión | KYC vinculado, paid_at, converted_at |
Acciones y modales
- Guardar configuración del comerciante: envía
PUT /v1/admin/payment-requests/merchants/:userId/config. La modificación de la comisión exige step-up (re-autenticación contraseña+MFA, headerX-Step-Up-Token). - Guardar split: envía
PUT /v1/admin/payment-requests/merchants/:userId/fee-split(o/fee-split/globalpara la plantilla default). Exige step-up y el backend valida que la suma de las fracciones es igual a la comisión (Σ pctOfGross == feePct); una divergencia es rechazada. - Aprobar / Rechazar KYC: envía
PATCH /v1/admin/payment-requests/kyc/:id/review. En el rechazo informe el motivo (rejectionReason). Use las acciones inline en la fila (no el menú de 3 puntitos). - Auditar cobro: abrir un cobro de la lista muestra el detalle y el journal de traspasos; es lectura/soporte, sin acción financiera.
Reglas de negocio / cuidados
Atención
- La comisión es una fracción, no un porcentaje.
0.03significa 3%. Digitar3cobraría 300%. Lo mismo vale para cadapctOfGrossdel split. - La suma del split tiene que coincidir con la comisión. Si las fracciones de las filas activas no suman exactamente la
feePct, el guardado es rechazado. - La comisión y el split se congelan en la creación de cada cobro (snapshot). Alterar la configuración después no afecta los cobros ya abiertos — solo los nuevos.
- El alcance MERCHANT sobrepone el GLOBAL por completo. Si crea una fila MERCHANT, configure todas las filas de ese comerciante (costo operativo + socios); la plantilla GLOBAL deja de valer para él.
- Los socios deben ser usuarios con saldo USDT. En modo TEST el traspaso es crédito USDT en el ledger; en modo REAL los socios reciben en BRL en las cuentas internas y el comerciante recibe USDT.
KYC es captura-y-sigue
La revisión del KYC del pagador es post-pago: al enviar documento y selfie, el pagador ya ve el PIX y paga. Rechazar el KYC en la cola NO deshace un pago ya realizado ni revierte la conversión — es decisión de compliance/auditoría. El efecto de un rechazo (bloquear al comerciante, abrir investigación) es proceso operativo, no automático.
- Valores financieros: tratados como BigNumber en todo el cálculo (bruto, comisión, neto, USDT) — sin redondeo; verifique las casas decimales.
- Conciliación por valor: el cobro solo se finaliza si el valor del PIX recibido coincide exactamente con el valor del cobro (anti-colisión de identificador). Underpayment/overpayment no concilia.
- Idempotencia: marcar pagado, orden de conversión, crédito del comerciante, cada crédito de split y el usage BLS usan claves estables por transacción. Reprocesar es seguro — FinLib retorna
E00021("already processed"), que es éxito, no error.
Ejemplos
Escenario 1 — Comerciante con comisión de 3% y split de 0,30% casa + 2,70% socios
El operador busca al comerciante u-5678, define comisión 0.03, habilita pagos y registra nombre de visualización y clave PIX. En la pestaña Split, crea 4 filas MERCHANT: OPERATIONAL_COST con pctOfGross 0.003 (retención de la casa, BRL) y tres PARTNER con 0.009 cada uno (socios, USDT) — suma 0.03, igual a la comisión. En un cobro de R$ 100 pagado, el comerciante recibe ~R$ 97 en USDT, los socios reciben el equivalente a R$ 2,70 en USDT y R$ 0,30 queda retenido en BRL en la casa.
Escenario 2 — Revisar KYC de un pagador
En la cola, el operador abre un pagador PENDING_REVIEW, verifica el documento contra la selfie y los datos (nombre/CPF/nacimiento). Estando consistente, clica Aprobar — el registro pasa a APPROVED. Si hay inconsistencia (foto ilegible, datos divergentes), clica Rechazar con motivo; el estado se vuelve REJECTED, pero el pago ya hecho permanece — el rechazo se vuelve insumo de compliance.
Escenario 3 — Comerciante sin split (solo comisión)
El operador define solo la comisión 0.03 y habilita al comerciante, sin registrar filas de split. La comisión entera se vuelve retención de la casa (OPERATIONAL_COST) — útil cuando aún no hay socios registrados. Después es posible agregar las filas MERCHANT; los cobros ya creados mantienen el snapshot antiguo (sin split).