Integração com passarelas de pagamento: flow, reembolsos, reconciação

Texto completo do artigo

💡 18+. Material técnico para plataformas iGaming, operadoras e provedores de pagamentos. Não um apelo para o jogo.

1) Papel da orquestra de pagamento em iGaming

Caixa - «Artéria» da plataforma: ela aceita depósitos, inicia cachês, processa reembolsos/chargeback 'e sincroniza-se com a carteira (Ledger). Erro ou atraso se transforma rapidamente em risco financeiro e de complacência. O desafio da arquitetura é o fluxo de dinheiro rápido e comprovadamente correto em qualquer falha.

2) Flow básico com PSP (mapa de estados)

2. 1 Depósito (cartão de estado)

1. create _ intent (INICIATED) → criar uma intenção de pagamento do lado de fora da plataforma.

2. ATHORIZED → uma colda no PSP (opcional - capture imediatamente).

3. 3-DS/AVS/KYC hooks → verificação de risco/regulação.

4. CAPTURE (CAPTURED) → cancelamento; carteira credit.

5. failed/expired/canceled → compensação e fechamento da intenta.

2. 2 Cachaça (withdrawal)

request → validação RG/AML/limites → payout _ iniciated → payout _ testled/failed.

Confirmação de «quatro olhos» para grandes quantias VIP, limites de velocidade e regras geo.

2. 3 Void / Refund

void: cancelamento até capture (retira hold).

refund: retorno parcial/completo após capture.

Para os esquemas de cartas, os estados individuais são «submitted/processed».

A verdade sobre o equilíbrio do jogador é a carteira. A aparência PSP não altera diretamente o equilíbrio; apenas através do comando 'wallet. credit/debit 'com idimpotência.

3) Idempotidade, chaves e retais

Cada operação write traz «X-Idempotency-Key» e «X-Trace-Id».

A composição da chave está vinculada a parâmetros empresariais (por exemplo, 'intent _ id + amount + currency').

A repetição com a mesma chave → o mesmo resultado (200 com o antigo body).

Retraias com backoff exponencial + jitter, rígido 'timeout/deadline'.

4) 3-DS, AVS, velocity, antifrode

3-DS 2. x: preferencialmente challenge-flow com device-fingerprinting; Guarde o ECI/CAVV/DSTransID na revista.

AVS/CVV: inclua códigos de verificação na telemetria e regras de routing.

Velocity: limites de soma/quantidade/cartão/ASN/dispositivos (1h/24h/7d).

Sinais comportamentais: discrepância geo/horário, muitos cartões/poucos depósitos, caixas rápidas.

5) Routing e cascatas PSP

Regras: geo, banda BIN, tipo de cartão, custo, conversão, risco-screen.

Cascata: PSP1 → PSP2 em falha, sem perda de cesta (idempotent tocen).

A/B/multi-armed bandit: otimização da conversão e do custo.

Fail-open/closed: para erros duvidosos, aplique o safe-default (por exemplo, uma repetição através de outro merchant), mas não para o duble-capture.

6) Contratos API (fatias de referência)

6. 1 Criação de um intente em depósito


POST /v1/cashier/intents
Headers: X-Idempotency-Key, X-Trace-Id
{
"player_id":"p_123",  "amount":{"amount":50. 00,"currency":"EUR"},  "method":"card",  "metadata":{"brand_id":"A","region":"EU"}
}
→ 201 { "intent_id":"pi_001","status":"INITIATED" }

6. 2 Autorizações/Capture


POST /v1/cashier/intents/pi_001/authorize
→ 200 { "status":"AUTHORIZED","psp_ref":"psp_aa1","eci":"05","cavv":"…" }

POST /v1/cashier/intents/pi_001/capture
→ 200 { "status":"CAPTURED","capture_id":"cap_001" }

6. 3 Void / Refund


POST /v1/cashier/captures/cap_001/refunds
{ "refund_id":"rf_001", "amount":{"amount":10. 00,"currency":"EUR"} }
→ 202 { "status":"REFUND_SUBMITTED" }

6. 4 Webhooks PSP → plataforma (HMAC/EdDSA assinados)


POST /webhooks/psp
X-Signature: sha256=…
{
"event":"payment. captured",  "psp_ref":"psp_aa1",  "intent_id":"pi_001",  "amount":{"minor_units":5000,"currency":"EUR"},  "occurred_at":"2025-10-23T12:05:01Z",  "idempotency_key":"cap_001"
}

O receptor é obrigado a verificar a assinatura/temporizador/nonce, deduzir 'event _ id', correlacionar com 'intent _ id'.

7) Sincronizar com a carteira (Ledger)

Depois de capture: comando 'wallet. credit '(idimpotente) → o equilíbrio do jogador.

Refund: `wallet. debit '(ou' wallet. hold _ release 'para void).

Cashaut, 'wallet. debit` → `payout` в PSP; depois do webhook 'payout _ massled' é o encerramento da saga.

A saga «deposit» é 'athorize' capture 'credit' com compensações por rejeição.

A saga «refund/payout»: 'request → submitted → massled/failed' com repetição e dedução.

8) Reconciliação - coração do controle do dinheiro

8. 1 Conciliação diária

Obter o relatório PSP Senslement (em merchant/data/moeda).

Corresponder ao registro de plataforma: 'intents/captures/refunds/payouts' n' wallet entries '.

Categorizar:

match: tudo ok, timing: atraso mіzh relatórios, missing _ psp: a plataforma tem, não há no PSP, missing _ platch: o PSP tem, não tem, amount _ mismatch: divergência de valor/moeda/fee.
Regras auto para timing, tíquetes/escalação para mismatch.

8. 2 Processo de processo

Os relatórios são puxados por SFTP/API programado (retrai + controle de integridade).

Parsing → normalização → mapping determinado ('psp _ ref', 'intent _ id', 'capture _ id').

O cruzamento é feito no OLAP (ClickHouse/BigQuery) por invariante.

Vitrines BI: conversões, razões de rejeição, custos de canais, hora de fechamento.

8. 3 Alertas

`% mismatch` > X p. p., saliência de 'missing _ platformar', altura de 'amount _ mismatch', desvio de 'deposit _ success' pelo canal/geo, aging de transações não válidas> N dias.

9) Chargeback / Dispute

Ciclo de vida: notificação → evidence → representment → arbitration.

Armazene os pacotes de evidence (KYC, IP/ASN, device, resultados 3-DS, usage-logs).

Conexão estreita com risk/anti-fraud: bans de mapas/dispositivos/ASN no nível de routing.

KPI: win-rate, cost-to-serve, time-to-close.

10) Telemetria e SLO

p95 permissões: ≤ 3 c, p99: ≤ 6-8 s (depende de 3-DS/bancos).

Deposit sucess rate por geo/PSP: meta ≥ 85% (referência realista).

Reconciação lag: relatório encerrado ≤ T + 1 dia; aging dos inválidos

Refund turnaround: ≤ T + 1 para envio, ≤ T + 5 para inscrição (padrão).

Métricas: erro-rate por código, falha por 3-DS/AVS, decline-matrix (banco/código), cux per sucess, webhook-lag, retry storms.

11) Segurança e Complacência

mTLS para PSP + OAuth2/assinaturas de solicitações; chaves/certificados per brand/region.

PCI DSS: localização PAN, nunca armazenamento CVV, segmentação de áreas.

Auditoria WORM: Operações de creme (manual refund/void, alteração do merchant).

RG/AML: estoques antes de capture/payout; folhas de sank/RER; Relatório SAR/TR.

PII residência: logs/relatórios na região; RLS/disfarce em BI.

12) Observabilidade e registro

Logs estruturados (JSON) com 'trace _ id', 'psp _ ref', 'intent _ id/capture _ id/refund _ id', códigos e longas.

OpenTelemetry em HTTP/gRPC/DB/filas; 100% de sampling para erros/anomalias monetárias.

Dashboards NOC: conversões por canal, p95, falha por código, webhook-lag, DLQ.

13) Práticas de caos e Dr

A queda do PSP é Auto-Carro/« pause new captures ».

Atrasos de webhoop: Dedup + reconexão via pull-API.

Out-of-order: Idempotidade e máquina estática na plataforma.

Outage regional: ativo-passivo/ativo-ativo, RPO ≤ 5 min, RTO ≤ 30 min

14) Folhas de cheque

Plataforma/operadora

Todos os caminhos write com 'X-Idempotency-Key', 'X-Trace-Id'.
Routing/cascata PSP com telemetria e limites.
3-DS/AVS/velocity incluídos; regras risk e bans.
Webhooks assinados; Dedup por 'event _ id'; DLQ.
Sagas deposit/refund/payout; compensação sem «edição manual».
Cruzamento diário T + 1, vitrines mismatch, alertas.
Área PCI, localização PAN; Auditoria WORM de Operações Critas.
RG/AML estoques até capture/payout.

Integração PSP/Backend da caixa

Os contratos de erro foram normalizados; mapping de códigos decline.
As repetições são seguras; as chaves de idimpotência estão documentadas.
Time-outs/retrai/jitter, circuito breaker, rate limits.
Os repostos estão disponíveis por API/SFTP, garantindo a integridade.

15) Anti-pattern (bandeiras vermelhas)

O equilíbrio é alterado pelo webhoop PSP sem um comando explícito para a carteira.

Não há idempotação → duplo cancelamento/crédito.

Caixa embutida dentro do provedor de jogos iFrame (perda de controle RG/AML/telemetria).

Chaves de merchant compartilhadas em várias marcas/regiões.

Nenhum cruzamento T + 1, Excel manual.

BI/relatórios regulatórios diretamente com caixa OLTP.

Os erros 3-DS/AVS não são ou não analisados.

Webhooks sem assinatura/validação da janela → da réplica.

Editar manualmente os estados de pagamento/balanço na base de dados.

16) Resultado

A integração com as passarelas de pagamento é uma orquestra, não uma «API». O sucesso garante:

1. Comandos de dinheiro Idempotentes e sagas (athorize/capture/refund/payout).

2. Routing e cascatas PSP com 3-DS/AVS/velocity e telemetria real.

3. Reposição diária e contabilidade rigorosa das divergências.

4. Segurança e complacência (mTLS, assinaturas, PCI, RG/AML, WORM).

Ao construir estes fundamentos, a plataforma aumenta a conversão de depósitos, reduz os riscos de duplicações e charjbacks e passa por uma auditoria segura - mesmo no auge do tráfego e em casos de falhas de provedores externos.