Uma API bancária para pagamentos em alto volume precisa combinar capacidade de processamento com mecanismos para lidar com picos, falhas e reprocessamentos. Idempotência, rate limits conhecidos, retries seguros, webhooks, filas, identificadores únicos, observabilidade e uma estratégia para recuperar eventos perdidos são alguns dos recursos necessários para processar grandes volumes sem gerar pagamentos duplicados ou perder informações.
Velocidade, sozinha, não resolve o problema.
Uma API pode responder rapidamente em condições normais e apresentar dificuldades justamente quando milhares de requisições chegam simultaneamente.
Também pode processar corretamente um pagamento, mas perder a conexão antes de responder ao sistema da empresa.
É nesses cenários que a arquitetura começa a fazer diferença.
O que significa processar pagamentos em alto volume?
Não existe um número universal que defina alto volume.
Para uma empresa, 10 mil pagamentos por mês podem representar uma operação relevante. Para outra, milhões de transações fazem parte da rotina.
Mais importante que estabelecer um corte é observar três dimensões:
volume: quantas operações precisam ser processadas;
concentração: quantas podem chegar simultaneamente;
criticidade: qual é o impacto quando uma operação falha.
Um ERP que envia 100 mil pagamentos ao longo de um mês enfrenta um desafio diferente de outro que precisa processar grande parte desse volume em poucos minutos.
Por isso, média não conta toda a história.
Por que essa discussão ganhou importância?
O volume de transações digitais no Brasil continua aumentando.
Segundo a Febraban, o sistema bancário brasileiro registrou 208,2 bilhões de transações em 2024, sendo 82% realizadas por canais digitais.
No Pix, a escala também é significativa.
Segundo o Banco Central, o Sistema de Pagamentos Instantâneos liquidou R$ 29,61 trilhões em 2025. Somente em dezembro daquele ano foram 7,10 bilhões de transações Pix interbancárias.
Para empresas que participam dessa economia digital, pagamentos deixam de ser apenas uma função bancária.
Passam a fazer parte da arquitetura de software da operação.
LEIA MAIS:
O que é uma API? Definição, funcionamento e TUDO sobre
Pagamento em lote: como automatizar milhares de transferências e pagamentos de fornecedores
Cobrança em lote: como automatizar faturamento massivo e faturas de consumo de concessionárias
O que é throughput?
Throughput é a quantidade de operações que um sistema consegue processar em determinado intervalo.
Pode ser expresso, por exemplo, em:
transações por segundo (TPS).
Uma API pode apresentar baixa latência e ainda possuir capacidade insuficiente para determinado pico.
Imagine que cada requisição responda em 150 milissegundos.
Isso parece rápido.
Mas, se a operação precisar enviar dezenas de milhares de requisições simultaneamente e a arquitetura não suportar essa concentração, filas e erros podem surgir.
Por isso, ao avaliar capacidade, pergunte:
- qual volume sustentado a API suporta?
- como se comporta em picos?
- existem limites por cliente?
- esses limites podem ser ampliados?
- o que acontece quando eles são atingidos?
O que são rate limits?
Rate limits determinam quantas requisições um cliente pode enviar à API dentro de determinado intervalo.
Eles existem para proteger sistemas contra sobrecarga e distribuir capacidade.
O problema não é uma API possuir rate limit.
O problema é a empresa descobrir o limite em produção.
Se o ERP tenta enviar 20 mil operações em poucos segundos e ultrapassa o limite permitido, precisa saber como reagir.
Uma integração robusta pode:
controlar a velocidade de envio;
colocar requisições em fila;
interpretar respostas de limite;
aguardar;
tentar novamente.
Por isso, empresas com picos previsíveis deveriam discutir capacidade antes do go-live.
O que é idempotência e por que ela é importante em pagamentos?
Idempotência permite repetir uma requisição sem criar a mesma operação financeira duas vezes.
Imagine:
o ERP envia um pagamento de R$ 50 mil;
o banco processa;
a conexão cai antes da resposta chegar;
o ERP não sabe se funcionou.
O que fazer?
Se simplesmente enviar novamente, existe risco de pagar R$ 100 mil.
Com idempotência, as duas tentativas carregam um identificador que representa a mesma operação.
O servidor reconhece a repetição e evita criar um segundo pagamento.
Em APIs financeiras, isso é especialmente importante porque falhas de rede não significam necessariamente falhas da transação.
Retry significa simplesmente tentar novamente?
Não.
Retry precisa fazer parte da arquitetura.
Nem todo erro deve gerar uma nova tentativa.
Um erro temporário pode justificar retry.
Uma requisição inválida provavelmente não.
Também é importante evitar que milhares de sistemas tentem novamente exatamente no mesmo instante depois de uma indisponibilidade.
Estratégias de backoff aumentam progressivamente o intervalo entre as tentativas.
Um fluxo simplificado pode ser:
requisição → erro temporário → espera → retry → nova espera → retry
Quando combinado com idempotência, o sistema consegue repetir operações de forma muito mais segura.
Por que filas são importantes em alto volume?
Filas ajudam a separar o momento em que uma operação é criada do momento em que precisa ser processada.
Imagine 100 mil pagamentos aprovados simultaneamente.
Em vez de tentar enviar os 100 mil de uma vez, a aplicação pode colocá-los em uma fila.
Workers consomem as operações de acordo com a capacidade disponível.
Isso permite controlar:
- concorrência;
- rate limits;
- retries;
- prioridade;
- picos.
A fila funciona como uma camada de absorção.
O volume pode chegar rapidamente sem precisar ser processado todo no mesmo instante.
Webhook ou polling: qual usar?
Os dois modelos servem para descobrir mudanças, mas funcionam de formas diferentes.
No polling, o sistema pergunta repetidamente:
“o pagamento mudou de status?”
No webhook, o fornecedor informa:
“o pagamento mudou de status.”
Para grandes volumes, webhooks tendem a reduzir consultas desnecessárias.
Se existem 1 milhão de pagamentos pendentes, consultar continuamente cada um apenas para descobrir se algo mudou pode gerar enorme quantidade de tráfego.
Com webhook, o evento chega quando ocorre.
Mas isso não significa abandonar completamente mecanismos de consulta.
O que acontece se um webhook falhar?
Esse é um dos pontos mais importantes em uma integração financeira.
Webhooks dependem de comunicação entre dois sistemas.
O endpoint da empresa pode estar temporariamente indisponível.
A rede pode falhar.
O processamento interno pode apresentar erro.
Por isso, uma arquitetura robusta precisa considerar:
retry de entrega;
registro dos eventos;
identificadores únicos;
consulta de eventos não recebidos;
reconciliação posterior.
A documentação do Stark Bank, por exemplo, informa que, quando o endpoint não retorna HTTP 200, existem novas tentativas de entrega após 5, 30 e 120 minutos.
Se as três tentativas falharem, o evento deixa de ser reenviado automaticamente.
Por isso, a própria documentação recomenda manter uma rotina para consultar eventos não entregues.
Esse detalhe ilustra um princípio importante:
webhook acelera a comunicação, mas recuperação de eventos garante resiliência.
Webhooks podem chegar duplicados?
Sim.
Uma integração não deveria assumir que cada evento chegará exatamente uma vez.
Um evento pode ser reenviado.
Também pode chegar fora da ordem esperada.
Por isso, o consumidor precisa ser idempotente.
A documentação técnica utilizada pelo Stark Bank recomenda registrar os IDs dos eventos já processados e consultar o estado atual do recurso, em vez de depender exclusivamente da ordem de entrega.
Em operações financeiras, isso evita que a duplicidade de uma notificação produza uma duplicidade de efeito.
Como evitar pagamentos duplicados?
Evitar duplicidade exige mais do que uma única proteção.
Uma arquitetura pode combinar:
ID externo: identifica a operação criada pelo ERP.
Idempotência: impede que retries criem uma nova operação.
ID do pagamento: identifica o recurso criado no banco.
ID do evento: evita processar o mesmo webhook duas vezes.
Estado atual: confirma qual é a situação real da operação.
A documentação atual do Stark Bank informa que endpoints de escrita aceitam um identificador externo e que repetir uma requisição com o mesmo ID não duplica a operação.
Isso permite executar retries com maior segurança.
O que é observabilidade em pagamentos?
Quando algo dá errado, a empresa precisa descobrir o que aconteceu.
Imagine um fornecedor dizendo:
“não recebi”.
O financeiro pergunta para tecnologia.
Tecnologia precisa localizar aquela operação entre milhões de requisições.
Sem identificadores e logs estruturados, a investigação pode se transformar em uma busca manual.
Uma operação deveria ser rastreável entre:
ERP → requisição → pagamento → evento → transação → conciliação
Isso permite responder perguntas como:
quando foi enviada?
qual ID foi utilizado?
qual resposta retornou?
houve retry?
qual é o estado atual?
qual evento foi recebido?
qual movimentação financeira foi gerada?
Observabilidade reduz o tempo necessário para investigar exceções.
Latência ou throughput: qual é mais importante?
Os dois medem coisas diferentes.
Latência indica quanto uma requisição demora.
Throughput indica quantas operações podem ser processadas em determinado intervalo.
Uma API pode ter:
baixa latência + baixo throughput;
alta latência + alto throughput;
ou bons resultados nos dois indicadores.
Para pagamentos em massa, throughput e comportamento em picos podem ser tão importantes quanto o tempo individual de resposta.
Para experiências síncronas, como determinados pagamentos durante um checkout, latência ganha mais peso.
A arquitetura precisa refletir o caso de uso.
Uptime de 99,99% elimina a necessidade de resiliência?
Não.
99,99% de disponibilidade ainda admite aproximadamente 52 minutos e 34 segundos de indisponibilidade por ano, dependendo da forma de medição.
Além disso, a aplicação da empresa também pode falhar.
A internet pode falhar.
Um webhook pode não ser recebido.
Uma fila pode atrasar.
É por isso que sistemas financeiros não deveriam partir da premissa de que tudo sempre funcionará.
Uma arquitetura resiliente parte da pergunta:
quando alguma parte falhar, conseguimos continuar sem perder ou duplicar dinheiro?
Como testar uma API antes de colocar pagamentos em produção?
Um Sandbox deveria permitir testar mais do que o cenário perfeito.
A empresa deveria simular:
- pagamento aprovado;
- pagamento rejeitado;
- requisição inválida;
- retry;
- envio duplicado;
- webhook;
- webhook duplicado;
- endpoint temporariamente indisponível;
- mudança de status;
- consulta posterior;
- volume elevado.
O objetivo não é apenas provar que a API funciona.
É provar que a integração da empresa sabe reagir quando algo não funciona como esperado.
Como o Stark Bank lida com pagamentos em alto volume?
A documentação pública do Stark Bank informa atualmente 99,99% de uptime da API e latência mediana inferior a 200 milissegundos.
Para requisições de escrita, identificadores externos permitem repetir operações sem duplicá-las.
Os webhooks enviam eventos assinados digitalmente e possuem política de retry. Eventos não entregues também podem ser recuperados posteriormente pela API.
A documentação recomenda processamento assíncrono dos eventos e uso de filas ou job schedulers para separar o recebimento do processamento.
Outro ponto importante é capacidade.
Os limites de requisição são definidos por workspace e a própria documentação orienta clientes que esperam picos de tráfego a alinharem a capacidade antes da entrada em produção.
Esses mecanismos trabalham juntos.
Disponibilidade mantém a API acessível.
Idempotência protege retries.
Webhooks comunicam mudanças.
Filas absorvem picos.
Eventos recuperáveis ajudam a lidar com falhas.
Logs e IDs permitem investigar.
Checklist técnico antes de colocar uma API em produção
Antes do go-live, o time de tecnologia deveria conseguir responder:
- Qual é o volume médio esperado?
- Qual é o pico?
- Quais são os rate limits?
- O que acontece quando atingimos o limite?
- Operações de escrita são idempotentes?
- Quais erros devem gerar retry?
- Existe backoff?
- Como os pagamentos entram em fila?
- Quais mudanças geram webhook?
- O fornecedor faz retry de webhook?
- Como recuperamos eventos perdidos?
- Eventos podem chegar duplicados?
- Podem chegar fora de ordem?
- Como rastreamos uma operação ponta a ponta?
- Existe Sandbox?
- Conseguimos testar cenários de falha?
- Qual é o uptime histórico?
- Qual é a latência?
- Como a API se comporta em picos?
- Existe suporte técnico para incidentes críticos?
Se essas perguntas só surgirem depois que a operação estiver em produção, o risco já está dentro do processo.
Afinal, o que uma API bancária precisa ter para processar pagamentos em alto volume?
Uma API bancária para alto volume precisa combinar capacidade de processamento, disponibilidade e baixa latência com mecanismos de resiliência como idempotência, retries, rate limits conhecidos, filas, webhooks, recuperação de eventos e observabilidade.
Processar uma grande quantidade de pagamentos quando tudo funciona é apenas parte do problema.
A arquitetura precisa continuar consistente quando uma conexão cai, uma resposta demora, um webhook não chega ou milhares de operações aparecem simultaneamente.
Em pagamentos, escala não significa apenas fazer mais transações.
Significa conseguir fazer mais transações sem perder controle sobre nenhuma delas.
