Como avaliar Pix integrado à liberação de ciclos

Desenhe o caminho entre cobrança e máquina

O fluxo começa quando a máquina ou sistema cria uma cobrança Pix para um ciclo específico. O backend grava o ID da máquina, ciclo, valor, txid e data de expiração antes de mostrar QR Code ou código copia e cola. O usuário paga no aplicativo do PSP. O sistema recebedor obtém a situação por API/webhook ou consulta ao PSP, valida que cobrança e valor correspondem ao ciclo e então envia um comando único de liberação para o controlador.

O Manual de Padrões para Iniciação do Pix descreve cobranças vinculadas por txid, estados de cobrança e notificações webhook para Pix recebidos. O Banco Central publicou a versão 2.10.0 do Manual em agosto de 2026. Use a documentação vigente e o contrato/API do PSP que será integrado; o manual não define sozinho a lógica da máquina nem o fluxo de uma solução comercial específica.^{Manual Pix publicação da versão 2.10.0}

Desenhe também os caminhos de erro: cobrança removida, tempo de espera excedido, ciclo cancelado, controlador offline, pagamento confirmado depois do vencimento e estorno aprovado. Sem esses caminhos, o sistema pode cobrar e não liberar, ou liberar sem confirmação.

Trate status e repetição de eventos com segurança

No manual do Pix API, cobranças usam estados como ATIVA, CONCLUÍDA e estados de remoção pelo recebedor ou PSP. O estado CONCLUÍDA é final no fluxo de cobrança e indica que um Pix associado ao txid foi recebido, conforme manual. A tela da máquina não deve inventar um status alternativo; mantenha os eventos brutos e o estado normalizado que a integração definiu. Consulte a cobrança e reconcilie com PSP quando notificações faltarem ou houver inconsistência.

Uma webhook pode ser repetida ou chegar depois de outra chamada. Por isso, use chave de idempotência na lógica de negócio: o mesmo evento não pode criar dois comandos de partida para o mesmo ciclo. Grave o ID do evento ou endToEndId, txid, hora, valor, estado, máquina e resultado do comando. Faça a decisão de liberação de modo atômico para evitar duas notificações simultâneas ultrapassarem a mesma checagem.

Uma cobrança única deve estar associada a um único identificador de ciclo, mas o sistema também precisa tratar eventual pagamento extra ou cobrança duplicada como exceção financeira, sem iniciar uma nova lavagem automaticamente. Limite o ciclo liberado a uma única máquina e duração definida. A confirmação de pagamento e o sinal físico de partida são eventos distintos: registre ambos e mostre ao usuário o que fazer se o controlador não responder.

Teste atraso, expiração e falha de conexão

Defina um prazo de espera visível, mas não transforme o timeout em “pagamento recusado”. Uma webhook pode atrasar ou o sistema pode estar temporariamente sem conexão. Quando o tempo vencer, consulte o estado pela API do PSP antes de instruir pagamento de novo; caso contrário, um consumidor pode pagar duas vezes. Se a cobrança realmente foi removida ou expirou, gere outra cobrança vinculada a novo ciclo ou nova tentativa, com instrução clara para não reutilizar QR vencido.

Teste usuário paga no último instante, pagamento chega após refresh, conexão cai entre o retorno do PSP e a máquina, e pagamento é confirmado enquanto a tela do terminal está offline. O backend deve persistir a confirmação e retomar a entrega do comando idempotente quando o controlador voltar, respeitando a política de tempo da operação. Se o ciclo não puder mais ser usado, a interface deve conduzir a resolução de cobrança, cancelamento ou devolução de modo documentado; não deixe valor recebido sem reconciliação.

Inclua também diferença de valor, QR associado à máquina errada, notificação sem txid, repetição de evento, tentativa de alterar uma cobrança concluída e mudança de valor. Manual do Pix estabelece que cobrança concluída não pode ser alterada ou removida; crie uma cobrança nova para outra tentativa e mantenha trilha de auditoria.^{regras de cobrança e webhook}

Separe devolução comercial do Mecanismo Especial de Devolução

Uma devolução por ciclo cancelado ou serviço não prestado é tratativa comercial: localize o Pix original, determine quem autoriza, registre motivo, valor e confirmação, e acione o PSP por seu procedimento de devolução. O Manual Pix prevê consulta à cobrança e identificação do recebimento original para efetuar devolução. Guarde o identificador do pagamento de origem e associe o retorno ao registro da máquina, sem apagar a trilha.

O Mecanismo Especial de Devolução (MED) não é um botão geral de estorno para qualquer insatisfação. A FAQ atual do Banco Central o restringe a suspeita fundada de fraude e falha operacional no ambiente Pix, entre outras condições do regulamento. Uma cobrança duplicada por erro do próprio sistema de integração pode exigir análise do PSP; não prometa que MED substitui o processo de reembolso normal. Explique ao cliente o canal de suporte e prazo previsto no procedimento contratado.^{FAQ do MED}

Se o ciclo foi liberado antes de perceber pagamento irregular, registre o ocorrido para conciliar operação e recebíveis. Não deixe a equipe apagar a transação ou marcar “estornado” sem confirmação. O estado da cobrança Pix, a devolução, o comando da máquina e o atendimento do cliente são estados diferentes, embora ligados pelo mesmo identificador.

Concilie recebimentos com ciclos executados

O sistema precisa responder três perguntas: quanto foi cobrado, quanto foi recebido e qual ciclo foi efetivamente disponibilizado? Mantenha relatório por txid, identificador de Pix/endToEndId, valor, data, tarifa contratada se houver, ciclo, equipamento e status de liberação. Compare diariamente os eventos do PSP com o ledger local. Webhook melhora notificação para grandes volumes, mas a documentação BCB pressupõe infraestrutura apta a tratar o serviço e informa que notificações se associam a chave e recebimentos com txid; configure e monitore essa condição.

Defina regras de reconciliação para cobranças ainda ativas, concluídas, removidas, pagos sem associação conhecida e ciclos sem confirmação. Faça fila de exceções com responsável, prazo e evidência. Um relatório de vendas não substitui extrato de liquidação, e um extrato financeiro não prova que a máquina iniciou o ciclo. Preserve ambas as fontes para investigar divergência.

Se o PSP reporta taxa ou prazo de liquidação diferente do valor bruto, compare o bruto recebido ao valor líquido disponibilizado e ao contrato. Não invente taxa atual, prazo universal ou fornecedor recomendado. O custo dependerá do arranjo, instituição e contrato; a tela do usuário deve mostrar valor e condição antes do pagamento.

Faça os testes antes de cobrar um cliente

Use ambiente de homologação quando disponível e depois transações controladas de baixo valor com autorização operacional. Teste pelo menos: pagamento normal; pagamento que demora; webhook duplicada; webhook fora de ordem; QR expirado; cobrança removida; resposta do PSP indisponível; máquina offline; usuário fecha a tela após pagar; duas tentativas para o mesmo ciclo; valor divergente; cancelamento e devolução; reconciliação no dia seguinte. Registre entrada, evento esperado, resultado observado e recuperação.

Teste simultaneidade: dois clientes não podem liberar o mesmo equipamento ao mesmo tempo, e um pagamento não pode ser associado a ciclo de outra máquina. Simule o clique repetido no terminal e reenvio de webhook. Confirme se o controlador recebeu um comando só e se a tela mostra o resultado. Teste rollback quando o hardware rejeita o comando depois da cobrança confirmada.

Combine suporte em linguagem simples: “pagamento confirmado, aguardando máquina”, “ciclo liberado”, “confirme o pagamento no app” ou “fale com atendimento”. Não mostre sucesso só porque o usuário retornou de uma tela de pagamento ou anexou um comprovante. Confirmação deve vir do recebedor/PSP de forma verificável.

Inclua segurança do canal de notificação no roteiro técnico: validar a origem do evento conforme a API, proteger credenciais, limitar acesso de operação e registrar falha de assinatura ou formato. Uma resposta recebida pelo navegador do cliente não substitui a confirmação do PSP ao recebedor. Defina alarmes para webhook sem processamento, cobranças ativas antigas e pagamentos confirmados sem ciclo. Esses controles são requisitos de desenho da integração e devem ser verificados com o integrador; o Manual Pix define padrões da API, mas não audita a implementação da máquina.

Pergunte quem controla cada parte da integração

Antes de escolher a automação, pergunte quem cria cobrança, guarda credenciais, recebe webhook, valida assinatura, consulta API, controla txid, envia comando, impede duplicidade, reconcilia e processa devolução. Solicite diagrama, política de indisponibilidade, logs, retenção de dados e procedimento de suporte. Confirme se há um modo de operar quando internet ou energia falha, e o que ocorre com pagamento feito durante parada.

Peça também ambiente de teste, documentação de API, limites de taxa, mecanismo de repetição, prazo de webhook, suporte a QR dinâmico e estados de cobrança, e exportação de conciliação. Esclareça custos fixos e variáveis por canal, sem confundir tarifa Pix do PSP com preço cobrado pela plataforma ou serviço de automação. Condições dependem da instituição/contrato e precisam ser validadas, sem recomendação de fornecedor nesta página.

A integração está pronta quando o caminho nominal e os cenários de erro foram comprovados com a máquina e os registros financeiros. A SPL pode orientar a implantação operacional por meio da Mentoria, mas a solução técnica precisa ser apresentada e testada pelo fornecedor do sistema de pagamento e automação. Não há garantia de que um equipamento Speed Queen já venha com determinada integração; confirme a oferta para seu SKU.

Perguntas frequentes