O que metrologia me ensinou sobre gateways de pagamento

Como o erro se acumula

Para contribuições independentes, a incerteza combinada é a soma em quadratura:

u_c = sqrt(u1² + u2² + u3² + u4²)

A consequência prática disso é que a maior contribuição domina o resultado. Com u1 = 0,1, u2 = 0,1, u3 = 0,1 e u4 = 1,0, a combinada dá 1,015. Zerar completamente os três primeiros elos levaria o total para 1,0. Todo o esforço, e o ganho é de 1,5%.

Isso vale para erros independentes. Se as contribuições forem correlacionadas (todos os elos usando o mesmo padrão enviesado, ou todos medindo no mesmo ambiente com temperatura fora da faixa), elas somam linearmente:

u_c = u1 + u2 + u3 + u4

O acúmulo fica muito pior. Erro correlacionado é o problema mais chato da cadeia, porque você acha que está somando ruído quando na verdade está somando bias.

Existe uma regra prática de calibração industrial chamada TUR (test uncertainty ratio): o padrão usado precisa ser pelo menos 4 vezes mais preciso que a tolerância que você quer garantir. Para tolerância de ± 0,1 mm, o padrão precisa de incerteza melhor que 0,025 mm. Medir com precisão parecida com a tolerância é praticamente não medir.

Calibração não elimina erro

Calibrar não deixa o instrumento perfeito. Calibrar é levantar o erro dele em pontos específicos da faixa e, quando dá, corrigir o bias. Um instrumento calibrado não é um que não erra, é um que erra de forma conhecida e documentada.

Isso muda três coisas na operação: você sabe em qual faixa confiar no instrumento, sabe que ele deriva com o tempo e precisa voltar para o laboratório, e sabe se o erro atual é aceitável para a decisão que você vai tomar com aquele número.

Disponibilidade composta

Se cada elo tem disponibilidade independente, a disponibilidade fim a fim é o produto delas:

A_total = A1 × A2 × A3 × A4

Com números plausíveis:

Cada camada adicional custa por volta de 43 minutos de indisponibilidade por mês, mesmo que cada uma delas pareça excelente isoladamente. É o mesmo fenômeno do acúmulo de incerteza: você não consegue ser mais confiável que o produto dos seus elos.

O pior elo domina aqui também. Um gateway com 99,5% na frente de um participante com 99,95% resulta em 99,45%. Nesse cenário, melhorar a sua aplicação de 99,99% para 99,999% não muda nada no número que o seu cliente enxerga. É a estação rápida sendo otimizada enquanto o gargalo continua parado.

A conta acima assume falhas independentes. Se dois gateways diferentes liquidam pelo mesmo participante direto, eles não são redundantes: quando o participante cai, os dois caem junto. É exatamente o erro correlacionado da metrologia, que soma linear em vez de em quadratura.

O estado não é o mesmo em todo lugar

Esse é o problema mais silencioso da cadeia. Cada elo guarda uma cópia do estado do pagamento, e essas cópias não mudam ao mesmo tempo.

sequenceDiagram
  participant SPI as SPI (Bacen)
  participant PD as Participante direto
  participant GW as Gateway
  participant App as Sua aplicação

  SPI->>PD: liquidado em T0
  Note over PD: estado atualizado em T0 + 200ms
  PD->>GW: notificação
  Note over GW: estado atualizado em T0 + 900ms
  GW-->>App: webhook
  Note over App: estado atualizado em T0 + 2s<br/>(ou nunca, se o webhook falhar)

Entre T0 e o momento em que a sua aplicação atualiza existe uma janela onde você tem uma medição desatualizada sem saber disso. Se o webhook se perder, essa janela não fecha.

Os modos de falha dessa janela são conhecidos por quem trabalha com pagamento:

• Webhook perdido: o pagamento liquidou, o cliente pagou, e o seu sistema nunca soube. O cliente aparece no suporte com o comprovante na mão.
• Webhook duplicado: a mesma notificação chega duas vezes por retry. Sem idempotência, você credita duas vezes.
• Webhook fora de ordem: chega CONFIRMED depois de EXPIRED, porque foram por rotas diferentes.
• Timeout ambíguo: você pediu a criação de uma cobrança, deu timeout, e não sabe se ela existe do outro lado. É o pior tipo de erro, o que não te diz se aconteceu.

Repare que nada disso é erro aleatório. É erro sistemático. Consultar o mesmo gateway de novo não ajuda, porque se ele tem o estado errado ele vai devolver o estado errado de forma bem consistente. Para corrigir bias é preciso medir contra um padrão de nível superior.

Regulatório e compliance

Existe um risco em metrologia que não é técnico: o laboratório que calibra o seu padrão pode perder a acreditação. Da noite para o dia todos os certificados que ele emitiu ficam questionáveis e a sua cadeia de rastreabilidade fica inválida, mesmo com os instrumentos fisicamente perfeitos.

Na cadeia de pagamentos acontece a mesma coisa, e essa é a categoria de risco que menos aparece nas comparações de gateway:

• Quem responde ao Bacen é o participante direto. Se ele sofre sanção, tem a autorização suspensa ou entra em regime especial, todo mundo pendurado nele para de operar. Você não fez nada e mesmo assim está fora do ar.
• O contrato que sustenta a sua operação não é seu. O acordo entre o participante direto e o PSP intermediário pode mudar sem você participar da conversa. Uma mudança de política de risco em um elo que você nem conhece derruba o seu fluxo.
• Requisito novo desce a cadeia com atraso. Uma exigência do Bacen chega ao participante direto, que repassa ao PSP, que repassa ao gateway, que precisa expor aquilo na API para você conseguir cumprir. Cada tradução perde informação, e o prazo de adequação continua sendo o original.
• Compliance vira caixa preta. Quando o seu cliente é bloqueado por análise de risco, quem tomou a decisão? Em uma cadeia de quatro elos, descobrir isso vira um processo de dias por email, sobre uma regra que afeta diretamente a sua receita.
• A superfície de dados aumenta. Dados de transação e dados pessoais passam por mais um terceiro. Para LGPD, cada intermediário é mais um operador no fluxo, mais um contrato, mais um lugar para auditar e mais um ponto de vazamento possível.
• A custódia do dinheiro fica confusa. Entre a liquidação e o repasse para você, o recurso fica em conta de quem exatamente? Em cadeia longa a resposta costuma ser “de alguém no meio”, e o risco de crédito desse elo é seu.

Escolha o padrão de referência

Você precisa definir qual fonte é a verdade do seu sistema, e ela não pode ser o seu próprio banco. Na prática o mais próximo que dá para chegar é o extrato do participante direto, que é o elo mais perto do SPI ao qual você tem acesso.

Todo o resto (resposta de API, webhook, cache) é medição, está sujeita a erro e precisa ser conferida contra esse padrão periodicamente.

Reconciliação é calibração

Reconciliar não é tarefa contábil, é a calibração do sistema. Ela responde exatamente a pergunta metrológica: qual o erro atual da minha medição em relação ao padrão?

flowchart LR
  Extrato["Extrato do participante<br/>(padrão de referência)"]
  DB["Estado no seu banco<br/>(instrumento)"]
  Diff["Diff"]
  Metric["Métrica de divergência<br/>+ alerta"]

  Extrato --> Diff
  DB --> Diff
  Diff --> Metric

E o resultado precisa virar número, do mesmo jeito que um certificado de calibração vira número:

# HELP payments_reconciliation_divergence_total Divergências entre estado local e extrato
# TYPE payments_reconciliation_divergence_total counter
payments_reconciliation_divergence_total{type="missing_locally",provider="gw_a"} 12
payments_reconciliation_divergence_total{type="missing_upstream",provider="gw_a"} 0
payments_reconciliation_divergence_total{type="amount_mismatch",provider="gw_a"} 1

# HELP payments_state_lag_seconds Atraso entre liquidação na origem e atualização local
# TYPE payments_state_lag_seconds histogram
payments_state_lag_seconds_bucket{le="1",provider="gw_a"} 8420
payments_state_lag_seconds_bucket{le="5",provider="gw_a"} 9910
payments_state_lag_seconds_bucket{le="30",provider="gw_a"} 9998
payments_state_lag_seconds_bucket{le="+Inf",provider="gw_a"} 10000

Com o label provider você consegue comparar provedores entre si e alertar quando um deles começa a derivar. Sem essas métricas você não sabe o erro do instrumento, apenas confia nele.

Webhook não é fonte de verdade

Webhook é push: sem garantia de entrega, de ordem ou de unicidade. Ele serve para reduzir latência, avisando que alguma coisa mudou. A correção vem da consulta e da reconciliação.

async function onWebhook(event: GatewayEvent) {
  // sem validar assinatura, o sensor aceita qualquer entrada
  if (!verifySignature(event)) return reject()

  // idempotência pela chave do provedor, não por id gerado localmente
  if (await alreadyProcessed(event.endToEndId)) return ack()

  // não confia no payload: reconsulta o estado na origem
  const state = await gateway.getCharge(event.chargeId)

  // transição só avança, nunca regride
  await applyStateTransition(event.chargeId, state)

  return ack()
}

Os três pontos que mais evitam dor de cabeça:

• Idempotência pela chave de negócio do provedor. No Pix o endToEndId é estável ao longo de toda a cadeia, então ele funciona como chave mesmo se o pagamento passar por vários elos.
• Reconsultar em vez de confiar no corpo do webhook, que pode estar defasado até em relação ao próprio gateway que o enviou.
• Máquina de estados monotônica. Uma cobrança que já está CONFIRMED não volta para PENDING porque chegou um evento antigo. É o equivalente a rejeitar leitura fora da faixa do instrumento.

Meça cada elo separadamente

Em metrologia, decompor a incerteza serve para saber qual contribuição atacar. Aqui é a mesma coisa: medir só a latência fim a fim não diz onde investir.

Instrumentando por hop, com provider como label, aparecem coisas como “o gateway responde em 80 ms mas o participante atrás dele leva 1,2 s”. Sem essa decomposição você não sabe qual é o elo mais fraco, e sem saber qual é o elo mais fraco toda otimização vira aposta.

Faça a conta antes de escolher

Antes de assinar com um gateway, dá para fazer o mesmo cálculo que um metrologista faria, que é verificar se a incerteza total cabe na tolerância:

• Esse provedor é participante direto? Se não for, quantos elos existem entre ele e o SPI? Vale perguntar isso explicitamente, porque é comum um produto se descrever como “conexão Pix” sem deixar claro que liquida por três camadas.
• Qual disponibilidade eu preciso entregar para o meu cliente?
• Multiplicando os SLAs de toda a cadeia, eu chego nesse número?
• Quem é o participante direto na ponta? É o mesmo dos meus outros provedores?
• O que esse intermediário me entrega que compensa os elos que ele adiciona?

A lógica do TUR se aplica bem aqui. Se você precisa entregar 99,9% e escolhe um caminho que entrega 99,9% no melhor cenário, é o mesmo que medir tolerância de 0,1 mm com um instrumento de 0,1 mm de incerteza. Precisa de folga.

Redundância só vale se for independente

Ter dois gateways parece redundância, mas se os dois liquidam pelo mesmo participante direto o modo de falha é comum. Redundância de verdade exige caminhos que separam o mais perto possível da origem.

flowchart TB
  SPI["SPI"]
  P1["Participante A"]
  P2["Participante B"]
  G1["Gateway 1"]
  G2["Gateway 2"]
  App["Sua aplicação"]

  SPI --> P1
  SPI --> P2
  P1 --> G1
  P2 --> G2
  G1 --> App
  G2 --> App

Se os dois caminhos convergem em um único participante antes do Bacen, você tem duas integrações para manter e um ponto único de falha.

O custo de manter vários provedores

Essa é a saída mais comum de quem usa gateway. Como cada provedor sozinho não entrega a disponibilidade necessária, contrata-se dois ou três e coloca-se uma camada de roteamento na frente, que troca de rota quando um começa a falhar. Em confiabilidade isso é redundância paralela, e funciona: com dois caminhos independentes de 99,75%, a indisponibilidade dos dois ao mesmo tempo cai para 0,0006%.

O problema é que a conta de disponibilidade melhora e a de complexidade piora, e a segunda ninguém coloca na planilha antes de decidir:

• Cada provedor tem o seu modelo. Nomes de estado diferentes, códigos de erro diferentes, formato de webhook diferente, política de retry diferente. Você acaba escrevendo uma camada de tradução para um estado interno canônico, e essa camada vira o lugar onde os bugs aparecem.
• A reconciliação multiplica. Cada provedor tem seu extrato, seu horário de fechamento e seu jeito de identificar a transação. Reconciliar dois é mais que o dobro do trabalho de reconciliar um, porque agora existe o caso de a cobrança ter sido criada em um e paga pelo outro.
• O roteamento precisa de estado. Decidir qual provedor usar exige saber a saúde de cada um em tempo real, ter health check, circuit breaker e critério de volta. Roteador mal calibrado derruba tráfego bom ou insiste em rota morta.
• O failover em cima de operação em andamento é o caso difícil. Trocar de rota é simples para uma cobrança nova. Para uma cobrança já criada no provedor que caiu, não é: ela existe lá, pode ser paga a qualquer momento e continua sendo responsabilidade sua.
• A superfície de teste cresce junto. Sandbox de cada provedor, comportamento de cada um em timeout, e o cenário de failover, que é justamente o mais difícil de reproduzir e por isso quase nunca é testado.

O resultado é que você troca um problema de confiabilidade por um problema de engenharia, e passa a manter internamente algo parecido com um orquestrador de pagamentos. Para operação grande isso se paga. Para time pequeno costuma sair mais caro do que aparenta, e é bom notar que boa parte desse trabalho existe para compensar a instabilidade que os elos extras introduziram.

Vale a mesma ressalva do erro correlacionado: dois provedores só melhoram a disponibilidade se forem independentes de verdade. Se ambos liquidam pelo mesmo participante direto, você pagou todo esse custo de complexidade e continua com um ponto único de falha.