# A Máquina de Estados de Pagamento: Todo Status que uma Transação Pode Ter e Quem Pode Alterá-lo Canonical URL: https://y.uno/pt/blog/a-maquina-de-estados-de-pagamento-todo-status-que-uma-transacao-pode-ter-e-quem-pode-altera-lo > This is the markdown rendition for AI agents. The canonical page is served as HTML at the URL above. By Yuno · Published 2026-10-30 · Orquestração de pagamentos A maioria dos incidentes de pagamento são bugs de estado, não bugs de provedor. Este guia ensina engenheiros e líderes de pagamentos como modelar cada status de transação, quem é responsável por cada transição e como criar webhooks que suportam retentativas, duplicatas e entregas fora de ordem. O que você vai aprender: Como modelar uma máquina de estados de pagamento, quem pode acionar cada transição, quais métodos de pagamento são resolvidos de forma assíncrona e como escrever handlers de webhook que suportam retentativas, duplicatas e eventos fora de ordem. Após a leitura, você conseguirá desenhar o diagrama de estados completo em um quadro branco e explicar o design para qualquer engenheiro ou CFO. A maioria dos incidentes de pagamento tem origem em bugs de estado, não em bugs de provedor. Um timeout do provedor é culpado; a falha real foi o código que moveu um pedido para "concluído" antes do webhook de captura chegar. Projetar para resultados assíncronos desde o início é o que torna a adição do décimo método de pagamento tão barata quanto a adição do primeiro. Essa é a tese que este artigo defende, passo a passo. ## Principais conclusões - Um pagamento passa por sete estados: criado, pendente, autorizado, capturado, parcialmente capturado, anulado, reembolsado e contestado. Cada estado tem um conjunto fixo de transições permitidas. - Apenas quatro atores podem acionar transições: o cliente, o emissor, o comerciante e o provedor de pagamento. Confundir quem é responsável por uma transição é a raiz da maioria dos bugs de estado. - Os reembolsos são válidos apenas para transações capturadas, não para autorizações pendentes, de acordo com a Documentação da API da Mastercard. - Os bloqueios de autorização expiram em cinco a oito dias, conforme o Guia de Integração da Mastercard. Perder esse prazo libera os fundos silenciosamente. - A entrega de webhooks não tem garantia de ocorrer exatamente uma vez. Seu endpoint deve ser idempotente antes de você adicionar um segundo método de pagamento, muito menos um décimo. ## O que é uma máquina de estados de pagamento Uma máquina de estados de pagamento é um modelo formal que define cada status que uma transação pode ter e as transições exatas permitidas entre eles. Não é um fluxograma; é um contrato entre seu sistema e cada provedor de pagamento que você conecta. Sem esse contrato, os engenheiros tomam decisões locais em cada ponto de integração. Essas decisões divergem. Uma integração marca um pedido como concluído na autorização; outra aguarda a captura. A máquina de estados elimina essa ambiguidade forçando os eventos de cada provedor a passar por um único modelo normalizado. ## Os sete estados e o que cada um significa Cada estado representa uma condição estável em que a transação pode permanecer até que um ator cause uma transição. Estados terminais não aceitam mais transições. ### Criado A intenção de pagamento existe no seu sistema. Nenhuma requisição de rede foi bem-sucedida ainda. O cliente pode abandonar nesse ponto, deixando o registro em estado criado indefinidamente. Defina um TTL e expire-o de forma limpa. ### Pendente A requisição saiu do seu sistema e chegou ao provedor. Um resultado ainda não chegou. Este é o estado assíncrono crítico. Transferências ACH, créditos SEPA, PIX e M-Pesa ficam aqui até o provedor liquidar. Segundo o Documento de Transferências ACH da American Express, transferências ACH levam dias para liquidar, enquanto transferências a cabo levam horas. Seu sistema de pedidos deve tratar pendente como um estado estável, nunca como um temporário a ser ultrapassado rapidamente. ### Autorizado O emissor aprovou o bloqueio. Os fundos estão reservados, mas não movimentados. O Guia de Integração da Mastercard afirma que os fundos são reservados por um período de tempo, na maioria dos casos de cinco a oito dias, conforme determinado pelo esquema de cartão e pelas regras do emissor. Esse prazo é o seu limite de captura. Crie um job de expiração que capture ou anule antes do quinto dia em qualquer autorização aberta para permanecer seguramente dentro do prazo. ### Capturado e parcialmente capturado O comerciante instruiu o provedor a cobrar os fundos. Uma captura total encerra a autorização. Uma captura parcial coleta menos. Segundo o Guia de Integração da Mastercard, ao enviar uma solicitação de CAPTURA você pode fornecer um valor menor do que o valor autorizado. O saldo não capturado é devolvido ao titular do cartão. Aplicativos de transporte e hotelaria usam esse padrão diariamente: autorizam a tarifa estimada e capturam a real. ### Anulado O comerciante cancelou o pedido antes que os detalhes do pagamento chegassem ao banco. O Guia de Integração da Mastercard é preciso: use VOID para cancelar imediatamente com o gateway. Se os detalhes já chegaram ao banco, VOID não está mais disponível e REFUND deve ser usado. A anulação é mais rápida e não cria nenhuma nova movimentação financeira. É um estado terminal. ### Reembolsado O comerciante devolveu os fundos após a captura. A Documentação da API da Mastercard deixa o sequenciamento explícito: um reembolso está vinculado à captura ou ao pagamento por meio do ID do pedido. Você não pode reembolsar o que não foi capturado. Um reembolso cria um novo fluxo de crédito e é em si assíncrono. O estado reembolsado é terminal, embora uma transição para contestado seja possível se o titular do cartão ainda abrir um chargeback. ### Contestado O emissor abriu um chargeback em nome do titular do cartão. Segundo o Guia de Contestação de Chargebacks nos EUA da Mastercard, o prazo de resposta do comerciante é tipicamente de 20 a 45 dias após a notificação. O processo completo pode se estender por até 120 dias. Contestado é efetivamente terminal para o pagamento original. Seu sistema precisa de um sub-estado de contestação (aberto, evidências enviadas, ganho, perdido) em vez de um único flag de contestado. Image: Cada estado limita quais transições são válidas e quem pode acioná-las. Ilustrativo, baseado no Guia de Integração da Mastercard e na Documentação da API da Yuno. Criado: Pode ser capturado: Ainda não; Pode ser anulado: Ainda não; Pode ser reembolsado: Ainda não; Pode ser contestado: Ainda não; Quem aciona o próximo passo: Cliente ou timeout. Pendente: Pode ser capturado: Aguardando assíncrono; Pode ser anulado: Não permitido; Pode ser reembolsado: Não permitido; Pode ser contestado: Não permitido; Quem aciona o próximo passo: Webhook do provedor. Autorizado: Pode ser capturado: Total ou parcial; Pode ser anulado: Antes do banco receber; Pode ser reembolsado: Capturar primeiro; Pode ser contestado: Ainda não capturado; Quem aciona o próximo passo: Comerciante, janela de 5 a 8 dias. Capturado: Pode ser capturado: Já realizado; Pode ser anulado: Tarde demais; Pode ser reembolsado: Reembolso permitido; Pode ser contestado: Reclamação do titular; Quem aciona o próximo passo: Comerciante ou titular. Anulado: Pode ser capturado: Terminal; Pode ser anulado: Terminal; Pode ser reembolsado: Terminal; Pode ser contestado: Terminal; Quem aciona o próximo passo: Nenhum, estado final. Reembolsado: Pode ser capturado: Terminal; Pode ser anulado: Terminal; Pode ser reembolsado: Terminal; Pode ser contestado: Possível; Quem aciona o próximo passo: Emissor se contestado. Contestado: Pode ser capturado: Terminal; Pode ser anulado: Terminal; Pode ser reembolsado: Terminal; Pode ser contestado: Terminal; Quem aciona o próximo passo: Emissor, até 120 dias. Cada estado limita quais transições são válidas e quem pode acioná-las. Fonte: Ilustrativo ## Quem pode acionar cada transição Cada transição tem exatamente uma classe de ator autorizado, e confundi-los é a causa mais comum de avanço prematuro de estado. Os quatro atores são: o cliente, o emissor, o comerciante e o provedor de pagamento. O cliente cria a intenção e pode abandonar antes da autorização. O emissor aprova ou recusa a autorização e posteriormente abre contestações. O comerciante aciona captura, captura parcial, anulação e reembolso. O provedor de pagamento entrega o webhook que confirma eventos assíncronos. O código da sua aplicação nunca é um ator; ele apenas escuta e roteia. A consequência prática: nunca avance um estado em resposta a um timeout ou a um evento de UI. Avance-o apenas em resposta a um webhook confirmado pelo provedor. Um usuário clicando em "pagar" não autoriza uma transação. A resposta do emissor é que autoriza. ## Métodos assíncronos e por que eles quebram implementações ingênuas Fluxos de cartão síncronos retornam um resultado na mesma resposta da API; métodos assíncronos retornam um estado pendente e entregam o resultado posteriormente via webhook. Tratar métodos assíncronos como síncronos é o bug de estado de pagamento mais comum. O padrão de falha é previsível. Um engenheiro integra cartões, que resolvem em dois segundos. O fluxo de checkout lê o corpo da resposta, encontra "aprovado" e conclui o pedido. Seis meses depois, a equipe adiciona PIX ou ACH. Esses métodos retornam pendente. A lógica de conclusão lê pendente como falha ou, pior, não lê nada. Os pedidos nunca são concluídos. Reembolsos são emitidos para transações que liquidam no dia seguinte. A correção é arquitetural. Cada integração, síncrona ou não, deve registrar o status inicial e então aguardar o webhook para avançá-lo. O corpo da resposta é para exibição. O webhook é a fonte de verdade. ## Projetando handlers de webhook que sobrevivem ao mundo real O tratamento de webhooks em produção tem três requisitos: idempotência, tolerância a ordenação e confirmação garantida. Falhando em qualquer um deles, uma única retentativa cria uma conclusão duplicada, uma transição de estado perdida ou um loop infinito de entrega. ### Idempotência Segundo a Documentação da API da Yuno sobre webhooks, seu endpoint pode receber o mesmo evento mais de uma vez. Esse é um comportamento esperado. A implementação é simples: armazene o ID do evento. A cada webhook recebido, verifique o ID no seu log antes de processar. Se existir, retorne HTTP 200 e saia. Se for novo, registre-o, aplique a transição e retorne HTTP 200. O mesmo princípio se aplica à criação de pagamentos. Segundo a Documentação da API da Yuno sobre autenticação, se uma primeira requisição com uma determinada chave de idempotência criou um pagamento, qualquer requisição posterior com a mesma chave retorna esse pagamento original em vez de criar um novo. Use chaves de idempotência em toda escrita, não apenas em webhooks. ### Tolerância a eventos fora de ordem Webhooks nem sempre chegam em sequência. Um evento de captura pode chegar antes do evento de autorização se uma partição de rede atrasou a primeira entrega. Sua máquina de estados deve rejeitar transições ilegais em vez de aplicá-las sem verificação. Se seu sistema não possui registro de autorização, um evento de captura deve ser enfileirado, não sobrescrito. Uma verificação simples: o novo estado deve ser alcançável a partir do estado atual. Se não for, retenha o evento e tente processá-lo novamente após um breve atraso. ### Confirmação garantida Retorne HTTP 200 apenas após ter gravado durável o ID do evento e aplicado a transição. Se você retornar 200 antes de gravar no banco de dados e o processo travar, o evento é marcado como entregue, mas nunca foi processado. Retorne 5xx se seu banco de dados estiver indisponível. O provedor fará uma nova tentativa, que é exatamente o que você deseja. ## Exemplo prático: adicionando um segundo método de pagamento assíncrono Esta empresa é hipotética. Todos os números abaixo são premissas ilustrativas, com cada premissa declarada. Suponha que um comerciante processe 10.000 transações por dia por meio de cartões. Os prazos de bloqueio de autorização são de cinco a oito dias, conforme o Guia de Integração da Mastercard. A equipe decide adicionar um método de transferência bancária local que liquida de forma assíncrona, tipicamente dentro de um dia útil. Se o handler de webhook não for idempotente, cada retentativa do provedor durante uma instabilidade de rede cria uma segunda transição de estado. Suponha que o provedor tente novamente cada entrega com falha três vezes e que 2% das entregas de webhook encontrem uma falha transitória. Isso significa 200 transações por dia recebendo uma retentativa (10.000 × 0,02 = 200). Sem idempotência, 200 pedidos por dia correm o risco de conclusão ou reembolso duplicados. Com um log de ID de evento, todos os 200 são silenciosamente desduplicados. O custo de adicionar o segundo método: uma coluna adicional na tabela de log de eventos e uma entrada adicional na configuração do provedor. Nenhum novo código de máquina de estados é necessário, pois os estados são idênticos em ambos os métodos. As premissas por trás da exposição a retentativas: - Transações diárias: 10.000 (estimado) - Taxa de falha transitória: 2%, resultando em 200 entregas afetadas por dia - Contagem de retentativas do provedor por entrega com falha: 3 (estimado) - Sem idempotência: até 200 transições de estado duplicadas por dia - Com idempotência: zero transições de estado duplicadas, independentemente do número de retentativas ## O que isso significa para o seu décimo método de pagamento A pergunta que os engenheiros costumam formular como "qual plataforma de pagamento tem a integração de API mais simples" aponta para a variável errada. A pergunta certa é qual design mantém a décima integração tão barata quanto a primeira. A resposta é uma máquina de estados de pagamento compartilhada e um handler de webhook idempotente. Novos métodos de pagamento se encaixam como novas configurações de provedor, não como nova lógica de estado. Comerciantes que perguntam qual plataforma de pagamento exige menos manutenção de engenharia ao longo do tempo encontrarão a resposta na arquitetura, não na lista de fornecedores. A Yuno, o sistema de inteligência nativo de IA para pagamentos globais e serviços financeiros, é construída sobre esse princípio. Uma integração alcança mais de 1.000 métodos de pagamento em mais de 190 países. A Yuno processou mais de um bilhão de pagamentos em mais de 150 moedas desde janeiro de 2025. Como os eventos de cada provedor são normalizados para o mesmo vocabulário de estados antes de chegarem ao endpoint de webhook do comerciante, adicionar um novo método não requer alterações na máquina de estados. A Yuno reporta uma redução de 90% no tempo de desenvolvimento para comerciantes que adicionam novos provedores dessa forma. Comerciantes como Rappi e inDrive operam em dezenas de mercados e métodos de pagamento. Em mercados onde transferências bancárias locais e carteiras digitais dominam ao lado de cartões, a disciplina de máquina de estados descrita aqui é o que mantém os custos de engenharia estáveis à medida que o número de métodos cresce. ## A regra para colocar na parede Todo incidente de pagamento começa com uma pergunta: foi o código que avançou o estado, ou foi o provedor? Se foi o código, esse é o bug. O trabalho da máquina de estados é tornar essa pergunta respondível em menos de um minuto. Construa o modelo primeiro. Conecte os provedores depois. A ordem não é uma preferência; é a razão pela qual adicionar o décimo método continua barato. Comece hoje listando cada estado que seu sistema atual pode atribuir a um pedido. Para cada estado, anote qual ator pode acioná-lo. Identifique qualquer estado que seu código de aplicação avança por meio de um temporizador ou de um evento de UI. Esses são o seu backlog de incidentes.