Área de Pagamentos
Pré-requisitos de acesso
- Permissão (módulo):
managePaymentLinkConfig(configurar taxa e split),reviewPaymentKyc(fila de KYC),viewPaymentLinks(lista de cobranças) — cada aba exige o seu módulo. - Licença/Feature:
PAYMENT_LINKShabilitada na licença do tenant. - Contêiner do menu: GERAL → grupo Financeiro
O que é / quando usar
A Área de Pagamentos é onde o operador administra os links de cobrança PIX → USDT dos lojistas. Um lojista (usuário Midas-Web aprovado) gera links de cobrança que terceiros pagam via PIX; o líquido cai convertido em USDT no saldo interno do lojista, descontada uma taxa configurável que é a receita da casa.
Aqui o operador faz três coisas: configura cada lojista (taxa, habilitação, nome de exibição e chave PIX de recebimento), define o split da taxa (como a receita é repartida entre custo operacional da casa e sócios) e revisa a fila de KYC dos pagadores (documento + selfie). Há ainda a lista de cobranças para auditoria e suporte.
Pré-condições
- Permissão: o módulo correspondente à aba cadastrado para a role do operador (permissão dupla — enum CPM no backend + módulo dinâmico no DB; sem o módulo no DB a aba/ação não aparece, mesmo com o enum correto).
- Licença/Feature:
PAYMENT_LINKShabilitada na licença do tenant (Vault). Se desabilitada, a Área de Pagamentos nem aparece no menu. - Dependências de outras telas: o lojista precisa existir e estar
APPROVED. Para gerar links ele depende depaymentsEnabled = truena configuração e de uma taxa (ou split) definida. Sócios beneficiários do split precisam ser usuários da plataforma com saldo USDT.
Passo a passo
- Acesse Financeiro → Área de Pagamentos.
- Na aba Configuração do lojista, busque o lojista pelo
userId, ajuste taxa, habilitar pagamentos, nome de exibição e chave PIX, e salve (a confirmação da taxa pede step-up). - Na aba Split da taxa, monte as linhas de distribuição (custo operacional da casa + sócios) garantindo que a soma das frações seja igual à taxa, e salve (também com step-up).
- Na aba Fila de KYC, abra cada pagador pendente, confira documento e selfie lado a lado e aprove ou rejeite.
- Na aba Lista de cobranças, filtre por lojista/status/período para auditar cobranças e seus repasses.
Campos
Configuração do lojista (merchant_payment_config)
| Campo | O que é | Obrigatório? | Efeito no sistema/backend |
|---|---|---|---|
Lojista (merchantUserId) | Usuário Midas-Web alvo da configuração | Sim | Chave (merchant_user_id) de merchant_payment_config no PaymentManagementService (PGH). É o ID interno do usuário, não o e-mail. |
Taxa (feePct) | Taxa total cobrada sobre o bruto, em fração | Sim | Grava fee_pct (numeric fração). 0.03 = 3%. É o percentual descontado do bruto na conversão. Congelada na criação de cada cobrança (snapshot fee_pct_snapshot) — mudar aqui só afeta cobranças novas. Se houver split, deve ser igual à soma das linhas. |
Habilitar pagamentos (paymentsEnabled) | Liga/desliga a geração de links para o lojista | Sim | Grava payments_enabled (bool). Gate: com false o lojista não vê a Área de Pagamentos no Midas-Web nem cria links. |
Nome de exibição (displayName) | Nome do lojista mostrado ao pagador na página pública | Sim | Grava display_name. Aparece na SPA pública (pay.axiadigitalsolutions.com) para o pagador identificar de quem está pagando. |
Chave PIX (pixKey) | Chave PIX do lojista que recebe o PIX no modo REAL | Condicional (REAL) | Grava pix_key. Usada pela emissão do QRcode (bms-lib createStaticQRCode) — o PIX cai na conta do lojista. No modo TEST o PIX é stub e a chave não é exigida. |
Split da taxa (payment_fee_distribution)
| Campo | O que é | Obrigatório? | Efeito no sistema/backend |
|---|---|---|---|
Escopo (scope) | GLOBAL (template default) ou MERCHANT (por lojista) | Sim | Grava scope. Linhas MERCHANT sobrepõem por completo o GLOBAL do lojista (não mesclam). Sem linhas MERCHANT, valem as GLOBAL. |
Lojista (merchantUserId) | Lojista da linha, quando escopo MERCHANT | Condicional | Grava merchant_user_id (null em GLOBAL). |
Tipo (beneficiaryType) | OPERATIONAL_COST (retenção da casa) ou PARTNER (sócio) | Sim | Grava beneficiary_type. OPERATIONAL_COST fica retido em BRL na casa; PARTNER é creditado em USDT ao sócio. |
Sócio (beneficiaryUserId) | userId do sócio beneficiário | Condicional (PARTNER) | Grava beneficiary_user_id (null para custo operacional). O sócio precisa ser usuário da plataforma com account_balance USDT — o repasse é resolvido pelo userId. |
Fração sobre o bruto (pctOfGross) | Fatia da linha sobre o valor bruto, em fração | Sim | Grava pct_of_gross (numeric fração, ex. 0.027). A soma das linhas ativas precisa ser igual à feePct do lojista. |
Ativa (active) | Liga/desliga a linha | Sim | Grava active. Linhas inativas não entram no split nem na soma. |
Fila de KYC (payment_payer_kyc)
| Coluna | O que mostra | Origem do dado |
|---|---|---|
| Nome / Documento | Nome e CPF/CNPJ informados pelo pagador | full_name, document |
| Nascimento / E-mail | Data de nascimento e e-mail do pagador (recibo) | birth_date, email |
| Documento / Selfie | Imagens enviadas para revisão lado a lado | document_file_key, selfie_file_key (Storage payment-kyc/<token>/) |
| Consentimento / IP / UA | Trilha LGPD: consentimento, IP, User-Agent e timestamp | lgpd_consent, ip, user_agent, consent_at |
| Status de revisão | PENDING_REVIEW, APPROVED ou REJECTED | review_status, reviewed_by, reviewed_at, rejection_reason |
Lista de cobranças (payment_requests)
| Filtro/Coluna | O que mostra | Origem do dado |
|---|---|---|
| Lojista / Status | Lojista e estado da cobrança (Aguardando, Pago, Convertido etc.) | merchant_user_id, status |
| Valor / Bruto / Líquido | Valor cobrado, bruto recebido e líquido convertido | amount, gross_amount, net_amount |
| Taxa / Cotação USDT | Taxa congelada e cotação aplicada na conversão | fee_pct_snapshot, fee_amount, usdt_rate |
| Pagador | Pagador (mascarado), data de pagamento e conversão | KYC vinculado, paid_at, converted_at |
Ações e modais
- Salvar configuração do lojista: envia
PUT /v1/admin/payment-requests/merchants/:userId/config. A alteração de taxa exige step-up (re-autenticação senha+MFA, headerX-Step-Up-Token). - Salvar split: envia
PUT /v1/admin/payment-requests/merchants/:userId/fee-split(ou/fee-split/globalpara o template default). Exige step-up e o backend valida que a soma das frações é igual à taxa (Σ pctOfGross == feePct); divergência é rejeitada. - Aprovar / Rejeitar KYC: envia
PATCH /v1/admin/payment-requests/kyc/:id/review. Na rejeição informe o motivo (rejectionReason). Use as ações inline na linha (não o menu de 3 pontinhos). - Auditar cobrança: abrir uma cobrança da lista mostra o detalhe e o journal de repasses; é leitura/suporte, sem ação financeira.
Regras de negócio / cuidados
Atenção
- Taxa é fração, não percentual.
0.03significa 3%. Digitar3cobraria 300%. O mesmo vale para cadapctOfGrossdo split. - A soma do split tem que bater com a taxa. Se as frações das linhas ativas não somarem exatamente a
feePct, o salvamento é rejeitado. - A taxa e o split são congelados na criação de cada cobrança (snapshot). Alterar a configuração depois não afeta cobranças já abertas — só as novas.
- Escopo MERCHANT sobrepõe o GLOBAL por completo. Se criar uma linha MERCHANT, configure todas as linhas daquele lojista (custo operacional + sócios); o template GLOBAL deixa de valer para ele.
- Sócios precisam ser usuários com saldo USDT. No modo TEST o repasse é crédito USDT no ledger; no modo REAL os sócios recebem em BRL nas contas internas e o lojista recebe USDT.
KYC é captura-e-segue
A revisão do KYC do pagador é pós-pagamento: ao enviar documento e selfie, o pagador já vê o PIX e paga. Rejeitar o KYC na fila NÃO desfaz um pagamento já realizado nem reverte a conversão — é decisão de compliance/auditoria. O efeito de uma rejeição (bloquear o lojista, abrir investigação) é processo operacional, não automático.
- Valores financeiros: tratados como BigNumber em todo o cálculo (bruto, taxa, líquido, USDT) — sem arredondamento; confira as casas decimais.
- Conciliação por valor: a cobrança só é finalizada se o valor do PIX recebido bater exatamente com o valor da cobrança (anti-colisão de identificador). Underpayment/overpayment não concilia.
- Idempotência: marcar pago, ordem de conversão, crédito do lojista, cada crédito de split e o usage BLS usam chaves estáveis por transação. Reprocessar é seguro — o FinLib retorna
E00021("already processed"), que é sucesso, não erro.
Exemplos
Cenário 1 — Lojista com taxa de 3% e split de 0,30% casa + 2,70% sócios
Operador busca o lojista u-5678, define taxa 0.03, habilita pagamentos e cadastra nome de exibição e chave PIX. Na aba Split, cria 4 linhas MERCHANT: OPERATIONAL_COST com pctOfGross 0.003 (retenção da casa, BRL) e três PARTNER com 0.009 cada (sócios, USDT) — soma 0.03, igual à taxa. Numa cobrança de R$ 100 paga, o lojista recebe ~R$ 97 em USDT, os sócios recebem o equivalente a R$ 2,70 em USDT e R$ 0,30 fica retido em BRL na casa.
Cenário 2 — Revisar KYC de um pagador
Na fila, o operador abre um pagador PENDING_REVIEW, confere o documento contra a selfie e os dados (nome/CPF/nascimento). Estando consistente, clica Aprovar — o registro passa a APPROVED. Se houver inconsistência (foto ilegível, dados divergentes), clica Rejeitar com motivo; o status vira REJECTED, mas o pagamento já feito permanece — a rejeição vira insumo de compliance.
Cenário 3 — Lojista sem split (só taxa)
Operador define apenas a taxa 0.03 e habilita o lojista, sem cadastrar linhas de split. A taxa inteira vira retenção da casa (OPERATIONAL_COST) — útil quando ainda não há sócios cadastrados. Depois é possível adicionar as linhas MERCHANT; cobranças já criadas mantêm o snapshot antigo (sem split).