Como integrar Pix no seu sistema ou site (guia 2026)

Quais são os caminhos pra integrar Pix num sistema ou site?

São três caminhos: integrar direto na API Pix do banco onde a empresa tem conta, usar um gateway ou PSP que já entrega essa API com painel e webhooks, ou usar uma plataforma pronta de checkout que gera o Pix sem você programar nada. O certo depende do volume, do controle que você precisa e de quem vai manter a integração.

A especificação pública da API Pix, do Banco Central, define os mesmos endpoints pra toda instituição que a oferece. Mas cada banco tem portal, credenciais e certificado próprios, e a página do Pix Cobrança avisa que QR Code dinâmico, cobrança em lote e devolução são facultativos pra instituição. Confirme antes de escolher o banco.

Na maioria dos projetos que entregamos, o gateway é o ponto de equilíbrio: webhook, conciliação e devolução vêm prontos e o seu código fica pequeno. Foi o caminho do Mindbot, onde o bot gera a cobrança na BuckPay e o webhook libera a entrega na própria conversa do Telegram.

API direta do banco vale quando a tarifa começa a pesar e existe gente pra cuidar de certificado e conciliação. Se você vende pouco e só quer receber, uma plataforma pronta resolve sem software house.

QR Code estático ou dinâmico: qual usar no sistema?

Pra um sistema ou site, use QR Code dinâmico. O estático é basicamente a chave Pix impressa, às vezes com valor fixo, e serve pra balcão e pra quem recebe pouco. O dinâmico é gerado por pedido, carrega valor, prazo e um identificador único da cobrança, e é ele que permite ao sistema saber sozinho qual pedido foi pago.

Esse identificador é o txid. Pela especificação da API Pix, ele é criado pelo recebedor, é único por CPF ou CNPJ e, na cobrança imediata, tem de 26 a 35 caracteres alfanuméricos. Guarde o txid junto do pedido no seu banco de dados: ele é a chave da conciliação.

Sem identificador por venda, como no estático, o sistema só casa pagamento com pedido por valor e horário, e dois clientes pagando R$ 49,90 no mesmo minuto viram trabalho manual. Pior: a especificação diz que o webhook notifica apenas Pix associados a um txid, então pagamento direto na chave pode nem gerar aviso.

Como funciona uma cobrança Pix com vencimento?

A cobrança com vencimento é o Pix fazendo o papel do boleto: você define uma data, o pagador pode pagar até esse dia, e juros, multa, desconto ou abatimento entram na própria cobrança. Na API Pix ela se chama cobv, convive com a cobrança imediata, chamada cob, e pode ser criada em lote, o que ajuda quem emite muitas faturas por mês.

Pelo Banco Central, o Pix Cobrança liquida na hora e funciona 24 horas por dia, enquanto o boleto liquida em até 3 dias úteis. As modalidades da API se dividem assim:

• Cobrança imediata (cob). É a do checkout: o cliente paga agora. A validade é contada em segundos a partir da criação, e o padrão da especificação é 86.400 segundos, ou seja, 24 horas, se você não informar outro valor.
• Cobrança com vencimento (cobv). É a da fatura, da mensalidade e da conta: tem data de vencimento, dias de validade depois do vencimento e campos de juros, multa e desconto.
• Cobrança com vencimento em lote (lotecobv). Várias cobranças com vencimento numa requisição só.
• Cobrança recorrente (cobr). A cobrança ligada a uma autorização de Pix Automático.

Não trate cobrança com vencimento como se fosse imediata. Separe os dois fluxos: checkout usa cobrança imediata com prazo curto, fatura usa vencimento e régua de lembretes.

Como o sistema fica sabendo que o Pix foi pago?

Pelo webhook: você cadastra uma URL no PSP e ele chama essa URL quando um Pix ligado a um txid cai na conta. O seu sistema confere os dados, marca o pedido como pago e libera a entrega. Como o aviso pode atrasar ou se perder, o webhook precisa de um plano B: consulta ativa da cobrança e conciliação periódica.

Na API Pix, o webhook é configurado por chave Pix e protegido por mTLS, autenticação em que os dois lados apresentam certificado. A especificação deixa o prazo do aviso a cargo de cada PSP e permite agrupar vários Pix numa chamada, então o tratador precisa ler uma lista, não um pagamento só. Em gateway o formato muda, mas a lógica é a mesma.

Os cuidados gerais com webhook estão no guia de cobrança recorrente em SaaS. O específico do Pix: use o endToEndId, o identificador de 32 caracteres de cada Pix, como chave de idempotência. Mesmo aviso duas vezes, mesmo endToEndId, um processamento só.

E nunca libere pedido pelo que o navegador diz. Quem libera é o servidor, a partir do aviso do PSP ou da consulta à cobrança.

Como fazer conciliação e devolução de Pix?

Conciliação é comparar, com frequência fixa, o que o PSP diz que recebeu com o que o seu sistema marcou como pago. Devolução é o caminho inverso, e no Pix ela tem regra: sai pelo identificador do Pix original, não passa do valor recebido e precisa ser pedida dentro da janela que a especificação fixa hoje em 90 dias da liquidação.

A API Pix tem a consulta de Pix recebidos por período, com filtro por txid. Rode uma rotina diária, ou de hora em hora em volume alto, que procura pagamento sem pedido, pedido pago sem pagamento e valor diferente do cobrado. Pagamento sem pedido quase sempre é webhook perdido. Pedido pago sem pagamento é bug, e dos caros.

Pra devolver, a API usa o endToEndId do Pix original e um identificador de devolução criado por você. A especificação recusa identificador repetido pro mesmo Pix, o que deixa a devolução idempotente se o id vier do pedido, e o resultado final chega por webhook. Na documentação de Pix da Stripe, o reembolso também tem janela de 90 dias, aceita valor parcial e não pode ser cancelado.

Devolução que você pede é diferente de contestação. Quando o pagador alega fraude, o banco dele pode acionar o Mecanismo Especial de Devolução, o MED, e o dinheiro sai da sua conta por decisão do processo. Separe os dois no financeiro.

Na Velify, o Pix ao fornecedor sai pelo Mercado Pago e o reembolso volta pelo mesmo caminho, com cada pagamento registrado junto do pedido. É esse vínculo que transforma conciliação em rotina.

Dá pra cobrar assinatura com Pix Automático?

Dá, e é pra isso que o Pix Automático existe: o pagador autoriza uma vez no app do banco, define um valor máximo, e as cobranças seguintes são debitadas na data combinada, sem novo pagamento manual. A limitação hoje está na oferta: nem todo banco ou gateway disponibiliza o recebimento, e as condições mudam de um pra outro.

Pela página do Pix Automático no Banco Central, a empresa envia a cobrança ao banco do pagador nos dias anteriores, o banco agenda e notifica o cliente, e no dia debita pelas regras da autorização. Pagador não paga tarifa; recebedor pode pagar, conforme o prestador.

A documentação de Pix da Stripe, lida em outubro de 2026, diz que o Pix Automático não está disponível pra empresas domiciliadas no Brasil. Na prática, SaaS brasileiro que quer o recurso precisa de banco ou gateway nacional que já ofereça. Na API Pix, a recorrência tem endpoints e webhooks próprios.

Enquanto isso, Pix por fatura com lembrete resolve. O desenho completo de assinatura está no guia de cobrança recorrente.

O que dá errado na prática numa integração Pix?

Quase todo problema de Pix em produção cai em quatro grupos: aviso de pagamento que não chegou, pagamento em duplicidade, cobrança que expirou na hora errada e credencial vencida. Nenhum deles aparece num teste com um pagamento por vez, e todos aparecem nas primeiras semanas com cliente de verdade.

• Webhook perdido. O servidor estava fora, o certificado não bateu ou o aviso veio agrupado e o tratador leu só o primeiro item. O cliente pagou e o pedido segue pendente. Correção: consultar a cobrança pelo txid enquanto o cliente está na tela de pagamento e conciliar periodicamente.
• Pagamento duplicado. Pela especificação, a cobrança imediata paga fica concluída e não aceita outro pagamento. A duplicidade nasce fora dela: o sistema gera cobrança nova a cada clique em "gerar Pix" e o cliente paga duas, ou o mesmo aviso é processado duas vezes. Correção: reaproveitar a cobrança ativa do pedido, idempotência pelo endToEndId e devolução do excedente.
• Expiração. O padrão é 24 horas na API Pix e na documentação de Pix do Mercado Pago, que aceita de 30 minutos a 30 dias. Prazo curto demais deixa o cliente com um QR que não vale mais. E cancelar o pedido no segundo exato da expiração faz um aviso atrasado encontrar pedido cancelado com dinheiro na conta. Cancele com folga e preveja reabrir ou devolver.
• Certificado vencido. Na API direta do banco, o certificado do mTLS tem validade. Quando vence, cobrança e webhook param juntos. Coloque a data no monitoramento.
• Teste otimista. Simule aviso agrupado, atraso e reenvio antes de abrir pro público.

É aqui que as horas de uma integração de pagamento somem, bem mais do que na tela de checkout. Foi a mesma lição de construir o nosso gateway: o valor está em não perder pedido e não liberar nada duas vezes.

Quando vale contratar alguém pra integrar Pix?

Vale quando o Pix está no meio do seu produto: libera acesso, dispara entrega, repassa dinheiro a terceiros ou cobra assinatura. Se você só precisa receber vendas avulsas e conferir no extrato, o QR Code do banco ou uma plataforma pronta resolve, e pagar desenvolvimento pra isso é desperdício.

Na VTA, integração Pix entra como parte de um sistema ou SaaS, ou como projeto próprio de gateways de pagamento e de integração de APIs, sempre com escopo, prazo e preço fechados na proposta. Projetos a partir de R$ 20 mil; abaixo disso, a ferramenta pronta costuma ser a melhor escolha, e a gente fala isso na primeira conversa.

Se quiser avaliar o seu caso, conta pra gente qual sistema recebe o Pix, por qual provedor e o que precisa acontecer depois do pagamento. Respondemos no mesmo dia. Dá pra começar pelo pedido de orçamento ou direto no WhatsApp.

Perguntas frequentes