Como integrar Pix no seu site: o guia completo, do QR Code ao pedido liberado
01/10/2026 · Equipe FlowinPay
O Pix virou o jeito preferido de pagar no Brasil: cai em segundos, funciona a qualquer hora e não tem maquininha nem boleto para compensar. Para quem vende online, oferecer Pix no checkout deixou de ser diferencial — é o mínimo.
Receber Pix no seu site é simples, desde que o fluxo esteja certo. A maior parte dos problemas que vemos não é técnica: é o pedido sendo liberado antes de o dinheiro chegar, ou o sistema não percebendo que um pagamento caiu. Este guia mostra os caminhos possíveis, o fluxo completo de uma cobrança e os cuidados que evitam esses dois erros.
Três jeitos de receber Pix no seu site
Antes de escrever uma linha de código, vale saber que nem todo mundo precisa programar. Há três caminhos, do mais simples ao mais flexível:
| Caminho |
Para quem |
Precisa programar? |
| Checkout pronto ou link de pagamento |
Quem vende por Instagram, WhatsApp ou não tem site |
Não |
| Plugin para WooCommerce |
Lojas em WordPress |
Não |
| API REST |
Sistemas próprios, SaaS, bots, marketplaces |
Sim |
Checkout pronto. Você cria a página de pagamento no painel, com o nome e a imagem do seu produto, e compartilha o link. O cliente abre, vê o QR Code e paga. É o jeito mais rápido de começar a vender hoje.
WooCommerce. O plugin da FlowinPay adiciona o Pix como forma de pagamento da sua loja. O pedido muda de status sozinho quando o pagamento cai.
API. Quando você tem um sistema próprio — uma plataforma de cursos, um SaaS, um bot de Telegram —, a API dá controle total: você cria a cobrança, mostra o QR Code onde quiser e recebe o aviso de pagamento no seu servidor. É sobre esse caminho que o resto do guia fala.
O que você precisa antes de começar
- Uma conta aprovada num gateway de pagamentos. Na FlowinPay, o cadastro pede seus dados e documentos (KYC) — é o que permite receber em seu nome e sacar para a sua conta.
- Uma chave de API, gerada no painel. Ela identifica o seu sistema em cada chamada. Trate como senha: nada de colocar no código que roda no navegador ou num repositório público.
- Um endereço (URL) no seu servidor para receber os avisos de pagamento, os webhooks.
Como funciona uma cobrança Pix, do começo ao fim
- Seu sistema cria a cobrança. Quando o cliente fecha o pedido, o seu servidor chama a API informando o valor e uma descrição.
- Você mostra o QR Code e o "copia e cola". A resposta traz os dois, e também um link de pagamento pronto.
- O cliente paga pelo app do banco dele. Leva segundos, a qualquer hora do dia.
- O gateway avisa o seu sistema. Quando o pagamento cai, a FlowinPay envia um webhook
charge.completed para a URL que você informou.
- Seu sistema libera o pedido. Só agora: com o aviso conferido, você envia o produto, libera o acesso ou confirma a reserva.
Na prática, criar a cobrança é uma única chamada:
curl -X POST "https://app.flowinpay.com.br/api/v1/charges" \
-H "X-Api-Key: fpk_sua_chave" \
-H "Content-Type: application/json" \
-d '{
"value": 97.00,
"description": "Curso de fotografia — pedido 1042",
"callbackUrl": "https://sualoja.com.br/webhook/flowinpay",
"customer_name": "Maria Souza",
"customer_email": "maria@email.com"
}'
A resposta traz o br_code (o Pix copia e cola), a imagem do QR Code e o payment_link_url. A documentação da API tem todos os campos e exemplos em outras linguagens.
Os quatro cuidados que evitam dor de cabeça
1. Libere o pedido pelo webhook, nunca pela tela do cliente
É tentador liberar quando o cliente volta para o site dizendo "já paguei" — mas essa tela pode ser fechada, recarregada ou forjada. Quem confirma o pagamento é o webhook, que vem do gateway para o seu servidor. Se precisar mostrar "pagamento confirmado" na hora, consulte a cobrança pela API em vez de confiar no navegador.
2. Confira a assinatura de cada webhook
Qualquer pessoa pode tentar mandar um "pagamento confirmado" falso para a sua URL. Por isso cada aviso da FlowinPay vem com o cabeçalho X-FlowinPay-Signature, uma assinatura HMAC-SHA256 do corpo da mensagem feita com o segredo do seu webhook. Calcule a mesma assinatura do seu lado e só aceite o aviso se ela bater:
$corpo = file_get_contents('php://input');
$esperada = hash_hmac('sha256', $corpo, $segredoDoWebhook);
if (! hash_equals($esperada, $_SERVER['HTTP_X_FLOWINPAY_SIGNATURE'] ?? '')) {
http_response_code(401);
exit;
}
3. Prepare-se para receber o mesmo aviso duas vezes
Se o seu servidor demorar ou estiver fora do ar, o gateway tenta de novo — a FlowinPay faz até cinco tentativas, em intervalos crescentes. Isso é bom, porque você não perde o aviso, mas significa que o mesmo pagamento pode chegar mais de uma vez. Guarde o identificador da cobrança e, se ela já estiver paga no seu sistema, ignore a repetição. Assim ninguém recebe dois produtos por um pagamento.
4. Trate a cobrança que expirou
Cobrança Pix tem prazo. Se o cliente não pagar a tempo, ela expira (evento charge.expired) e não pode mais ser paga. Em vez de deixar o pedido parado, ofereça gerar uma nova — muitas vezes o cliente só se distraiu. Um e-mail de lembrete com um Pix novo muitas vezes recupera a venda.
Dica: antes de ir para produção, faça uma compra de verdade com um valor baixo, do começo ao fim. É o teste que mostra se o webhook chega, se a assinatura confere e se o pedido muda de status sozinho.
Depois de integrar
Com as cobranças funcionando, o resto fica no painel: acompanhar as vendas, sacar para a sua conta e, se algum comprador contestar um pagamento pelo MED, ver a defesa que a plataforma monta automaticamente. Sobre isso, vale ler como reduzir contestações de Pix. E se você vende assinatura, conheça o Pix Automático, que cobra todo mês sem o cliente precisar pagar de novo.
Perguntas frequentes
Preciso ter CNPJ para receber Pix no meu site?
Não necessariamente. Na FlowinPay dá para abrir a conta como pessoa física (CPF) ou como empresa (CNPJ). Em qualquer caso a conta passa por uma verificação de identidade, com documento e selfie, analisada em até 24 horas úteis.
Quanto tempo o dinheiro do Pix leva para cair?
O pagamento é confirmado em segundos, a qualquer hora, inclusive fins de semana e feriados. O aviso para o seu sistema sai assim que a confirmação chega.
Qual a diferença entre o QR Code e o Pix copia e cola?
Nenhuma no pagamento: os dois carregam a mesma cobrança. O QR Code é para quem paga no computador e lê com o celular; o copia e cola é para quem já está no celular e cola o código no app do banco. Mostre os dois.
Posso integrar Pix sem saber programar?
Sim. Com o checkout pronto você cria a página de pagamento no painel e compartilha o link; com o plugin do WooCommerce, o Pix entra na sua loja sem código.
O que acontece se o meu servidor estiver fora do ar quando o pagamento cair?
O pagamento não se perde. O gateway tenta entregar o aviso de novo algumas vezes, e você também pode consultar a cobrança pela API a qualquer momento para saber se ela foi paga.
