Confecção de pagamentos e relatórios PSP

TL; DR

O cruzamento é uma combinação automatizada diária do seu ledger e eventos (auth/capture/refund/payout) com relatórios PSP/Equiers/Bancos. A chave para o sucesso é um único modelo de dados, chaves de mapeamento determinadas, idempotidade rigorosa, tolerance de soma/FX/tempo, fila de DLQ para malas disputadas e playbooks de correção automática. KPI: Recon Mismatch Rate↓, Aging of Unreconciled↓, Auto-match%↑.

1) Porquê e o que fazemos

Metas: confirmação de receitas e comissões, detecção de tomas/perdidas, senslement correto por dias e moedas, controle de refund-to-nature, conformidade com a auditoria/regulador.

• Deposits: `auth → capture → settle`
• Refunds: full/partial, estatais e somas
• Payouts/Withdrawals: pagamentos de saída de métodos
• Fees & Adjustments: comissões PSP, esquema de interchange, correção
• Chargebacks/Disputes: fora da sua iniciativa
• FX/Conversões: cursos, spreads, momento de fixação

2) Fontes de dados

Internacional Events (seu): pneu de eventos/Kafka, 'payments _ flat', 'refunds',' payouts ', seu ledger.

• Transações (extratos operacionais)
• Setlents/Batches (notas de inscrição T + N)
• Fees/Status (comissões, ajustes)
• Chargebacks/Disputes
• Registos Payouts/OCT/RTP/SEPA
• Bank Statents: MT940/CSV/ISO20022 CAMT.

3) Chaves de mapeamento (matching keys)

1. provider _ txid ↔ provider _ txid (ID PSP exclusivo)

2. idempotency _ key/merchant _ reference (se estável em PSP)

3. (amount, currency, timestamp_bucket, last4/bin, auth_code)

4. Camada de fuzzy: £ tolerance em soma/tempo, BIN/issuer country, status de família

• Guarde os dois: 'payment _ id' e 'provider _ txid'.
• Para partial/refund - Adicione 'sequence _ index' ou 'refund _ line _ id'.
• Для payouts — `payout_batch_id + line_id`.
• Para FX - 'exec _ id' (conversão) e origem de curso.

4) Modelo de dados (camada normalizada)

json
{
"source": "INTERNAL    PSP_TX    PSP_SETTLEMENT    BANK",
"provider": "Acquirer_A",
"payment_id": "pay_123",
"provider_txid": "psp_tx_789",
"kind": "AUTH    CAPTURE    REFUND    PAYOUT    FEE    SETTLEMENT    CHARGEBACK",
"sequence": 0,
"amount": 100. 00,
"currency": "EUR",
"fee_amount": 1. 20,
"fx_rate": 1. 0000,
"fx_src": "PSP    ECB    BANK",
"status": "APPROVED    CAPTURED    SUCCESS    FAILED    SETTLED",
"event_ts": "2025-11-03T12:00:00Z",
"settlement_date": "2025-11-05",
"account": "PSP_MERCHANT_CARD_A",
"matching_keys": {
"provider_txid": "psp_tx_789",
"merchant_ref": "mr_456",
"idem_key": "idem_abc"
},
"hash_row": "sha256(...)"
}

5) Processo de conciliação (ETL/orquestração)

1. Ingest: Retiramos os relatórios PSP (SFTP/API), validamos o padrão/assinaturas e salvamos em 'raw'.
2. Normalize: mappim de campo em formato unificado (currency ISO, decimals, timsona UTC).
3. Match: algoritmo de mapeamento em madeira de chaves com tolerance.
4. Post-match: Formamos o diff (divergências) e o journal entries para o ledger/correção.
5. Setle: Curtindo 'PSP _ SETLEMENT ↔ BANK'.
6. Relatório: dashboard, alertas; disputado no DLQ para análise manual/auto-jogo.

Idempotidade: para cada arquivo/página - 'ingest _ id'. Carregar novamente não altera o resultado.

6) Tolerance (tolerances) e regras

Tempo: '£15 min' para transações, '£1 dn' para o senslement.
Soma: '≤ 0. 01 'moedas de base ou' ≤ 10 bps 'para FX/fee-parte.
FX: Permitimos uma divergência com o banco se a origem de taxa de câmbio for diferente; captamos 'fx _ src'.
Partial/Multiple: O montante das linhas partial/refund deve ser igual ao saldo interno.

7) Processamento de divergências (diff taxonomy)

8) Ledger & Accounting (cabos)

Capture: `DR Accounts Receivable / CR Revenue` и `DR Cash (upon settle) / CR Accounts Receivable`

Fee: `DR Fees / CR Cash or Payable`

Refund: fios invertidos proporcionalmente partidário

Chargeback: contas individuais e reservas sob disputa

FX reval: reavaliação diária do saldo de AR/dinheiro no curso 'fx _ src _ policy'

9) KPI e alvos

Auto-match% = linhas mapeadas automaticamente/todas as linhas (alvo ≥ 95%)

Recon Mismatch Rate = Linhas Difs/Todas as linhas (≤ 1-2%)

Aging of Unreconciled: p50/p95 dias em DLQ (p95 ≤ 3 dígitos)

Senslement Timeliness: proporção de batches costurados com banco D-dia (≥ 99%)

Fee Accuracy: divergências de comissões de provedores (≤ 0. 1% de circulação)

Duplicate/Orphan Invents: busca 0

10) Cortes SQL

10. 1 Mapeamento básico provider _ txid

sql
WITH i AS (
SELECT provider, provider_txid, kind, amount, currency, event_ts
FROM internal_norm
),
p AS (
SELECT provider, provider_txid, kind, amount, currency, event_ts
FROM psp_norm
)
SELECT
COALESCE(i. provider_txid, p. provider_txid) AS txid,
COALESCE(i. provider, p. provider) AS provider,
i.kind AS kind_internal, p. kind AS kind_psp,
i.amount AS amount_internal, p. amount AS amount_psp,
i.currency, p. currency,
CASE
WHEN i.provider_txid IS NULL THEN 'MISSING_INTERNAL'
WHEN p. provider_txid IS NULL THEN 'MISSING_PSP'
WHEN ABS(i. amount - p. amount) > 0. 01 THEN 'AMOUNT_MISMATCH'
ELSE 'MATCHED'
END AS recon_status
FROM i
FULL OUTER JOIN p USING (provider, provider_txid);

10. 2 Settlement ↔ Bank

sql
SELECT s. settlement_date, s. batch_id, s. currency,
s. amount_settled, b. amount_bank,
(b. amount_bank - s. amount_settled) AS diff
FROM psp_settlements s
LEFT JOIN bank_statements b
ON b. value_date = s. settlement_date
AND b. currency = s. currency
AND ABS(b. amount_bank - s. amount_settled) <= 0. 5;

10. 3 Aging DLQ

sql
SELECT diff_type,
COUNT() AS cnt,
PERCENTILE_CONT(0. 5) WITHIN GROUP (ORDER BY AGE(NOW(), created_at)) AS p50_age,
PERCENTILE_CONT(0. 95) WITHIN GROUP (ORDER BY AGE(NOW(), created_at)) AS p95_age
FROM recon_dlq
GROUP BY diff_type
ORDER BY cnt DESC;

11) Características de trilho/mala

Mapas: diferenças entre 'auth' e 'capture', ajustes tardios 'senslement', interchange/fee de esquema - linhas individuais.
A2A/Open Banking/RTP: confirmações instantâneas, mas possíveis 'reversal'; corte 'payout' e retornos.
Carteiras: muitas vezes perfeito 'provider _ txid', rápido 'refund'; Vigiem as linhas fee.
Vales: Sem refund simétrico - Reflita corretamente na política e relatórios.
Kripto: ele-chain hash-provider _ txid; confirmes N; A contabilidade das comissões da rede e dos possíveis rebates; curso - no momento da conversão.

12) Playbooks operacionais

Ressurgir MISSING _ INTERNAL: verificar a perda de webhooks/retrações, reinstalar ingestão e ativar a API de meia-entrada.
AMOUNT _ MISMATCH DE UM PSP: comparar arredondamentos/IVA/fee-modelo, solicitar um status corretivo.
O Senslement não é combinado com o banco: verificar o valor de data, comissão do banco, atrasos T + N; Aposto temporariamente no «Aspense Matt».
REFUND _ OVER em massa: paragem imediata de refandos automáticos, auditoria de idempotação, correção manual.
FX _ DRIFT: fixe o policy de origem de curso (ECB/PSP/BANK), repasse P & L-diferença.

13) Controle e segurança

Idempotidade ingestão: 'arquivo _ id + checksum' e registro de downloads.
Acessibilidade (RBAC) e controle de quatro olhos: para correções manuais/fios de revista.
Todos os jogos/difas/correções - em registro inalterado.
Qualidade de dados: esquemas, campos obrigatórios, validação de moedas/skale.

14) Dashboard e alertas

Widgets: Auto-match%, Mismatch Rate, Aging DLQ, Senslement Timeliness, Fee Accuracy, top PSP em difas, mapa de tipos difs.

• 'Auto-match% <90%' por provedor/dia → P1
• 'Aging p95> 3 dn' n' P2
• `AMOUNT_MISMATCH spike` → P1
• 'Bank≠Settlement' em valor/moeda → P0

15) Malas de teste (UAT/Prod)

1. Carregar novamente o mesmo arquivo → 0 efeitos colaterais (idempotidade).
2. Refanda parcial (linha 3) → soma igual, jogo sequence.
3. Conversão FX: Divergência de taxa de câmbio dentro de tolerance → jogo correto.
4. Duplicar provider _ txid no relatório → deadup e alert.
5. O webhook capture ausente fechou o gap e o status está alinhado.
6. Senslement batch com fee-line → uma divisão correta em Revenue/Fee/Net.

16) Erros frequentes e como evitar

Mistura de bases de comparação (compare 'attempt' vs' capture ') → mantenha a mesma granularidade.
A ausência de 'provider _ txid' no login perde a precisão do jogo.
Ignorar temporizão → deslocamento em datas de senslement.
Não há DLQ/retrações de divergências «eternas».
As edições manuais sem registro → a inoperância com o áudio.
Tolerance ímpar ou um jogo de pena ou «tudo no DLQ».

17) Folha de cheque de controle de implementação

• Normalização unificada e guias PSP/métodos/contas
• Árvore de chaves de mapeamento (txid → merchant _ ref → fuzzy)
• Tolerance por soma/hora/FX, política de origem de curso
• Inhestão Idempotente, DLQ, retais, alerts
• Confecção de Settlement↔Bank, Política de Suspense
• Dashboard KPI, relatórios de finanças/auditoria
• Playbooks e SLA de análise de malas de desenho

Currículo

O controle é uma disciplina de engenharia, como normalização, chaves confiáveis, tolerance, jogos automáticos e correções transparentes. Com este circuito, você estabiliza as receitas e as comissões, minimiza os buracos negros, acelera o encerramento do período e passa por uma auditoria sem dor: Auto- match%↑, Mismatch↓, Aging↓.