API de pagamento PIX explicada de forma simples

Uma API de pagamento PIX conecta seu cliente ao seu bolso: você cria uma cobrança, o usuário paga e um webhook avisa seu backend. O fluxo cabe em três chamadas: criar cobrança, redirecionar para o checkout e tratar o webhook. Qualquer stack serve, porque tudo se resume a requisições HTTP.

O que é um gateway de pagamento PIX

Um gateway de pagamento é o agente que conecta o seu cliente ao seu bolso, e é ele que faz o seu SaaS ganhar dinheiro. Quando alguém finaliza uma compra no site da Chili Beans, por exemplo, a etapa final gera um código PIX copia e cola. Esse pedaço da jornada é exatamente o que um gateway automatiza para você.

Você não precisa construir esse mecanismo do zero. Existem soluções prontas, como a AbacatePay e a Stripe, que expõem uma API para criar cobranças, gerar o QR Code PIX e confirmar o pagamento. O vídeo usa uma analogia útil: pense no gateway como um portal de Minecraft. Quando o usuário entra nele, ele vai para outra dimensão, o site do gateway, e você perde o controle direto sobre ele até o retorno.

Por que a AbacatePay foi escolhida no projeto

A AbacatePay é um gateway brasileiro feito para desenvolvedores, com documentação enxuta e integração simples. O criador do vídeo, Daniel Lima, destaca dois motivos para a escolha: uma das menores taxas do mercado, R$ 0,80 por transação, e uma API que não exige conhecimento avançado para começar.

Outro diferencial citado é o simulador de pagamento no ambiente de teste. Em vez de fazer transferências PIX de R$ 1 no celular para validar o fluxo, você clica em simular pagamento e a plataforma chama o seu webhook normalmente. Segundo Daniel, concorrentes como o Mercado Pago têm algo similar, mas com uma experiência menos fluida. Vale lembrar que taxas e recursos podem mudar; confira sempre a documentação atual antes de decidir.

Como criar uma cobrança via API de pagamento PIX

Criar uma cobrança é um POST HTTP para a API da AbacatePay com poucos campos obrigatórios. Antes de tudo, você cria uma chave de API no painel, na aba de integração, e a guarda em uma variável de ambiente. Essa chave vai no header de autorização de cada requisição.

Os campos principais são estes:

• externalId: um identificador único da cobrança no seu sistema, por exemplo o ID do pedido ou do áudio gerado.
• methods: o método de pagamento; no teste do vídeo, apenas PIX com frequência one-time (pagamento único) estava disponível.
• products: lista com name, description, quantity e price. Atenção: o preço é em centavos, e o mínimo é 100, ou seja, R$ 1,00.
• returnUrl: para onde o cliente volta se clicar em "voltar" dentro do checkout.
• completedUrl: para onde ele é redirecionado quando o pagamento é concluído.
• customer: dados do pagador, como e-mail; se o cliente ainda não existir, a API cria o registro.

Na resposta, a API devolve um objeto JSON com os dados da cobrança e, dentro de data, a URL do checkout. É essa URL que você abre para o usuário pagar. Se quiser ver os campos na prática, use o botão "try it" da documentação oficial: ele monta a requisição preenchida e mostra a resposta antes de você escrever qualquer linha de código.

O fluxo do usuário: do clique ao retorno

No projeto do vídeo, um SaaS de mensagens de voz com inteligência artificial, o CTA "gerar áudio" é, para o backend, uma criação de cobrança. O usuário preenche nome, e-mail e mensagem; ao clicar, o frontend chama a rota createIntent, que dispara o POST na AbacatePay e recebe a URL do gateway.

Dentro do checkout, a pessoa vê o valor, os produtos e o código PIX. Se ela clicar em voltar, é levada para a returnUrl, que aponta de volta para o seu site. Se completar o pagamento, o gateway redireciona para a completedUrl, que no exemplo incluía o externalId na query string. Esse ID permite uma dupla verificação no backend antes de entregar o produto.

Uma recomendação prática do vídeo: capture o e-mail do cliente antes do pagamento e envie o produto por e-mail depois. Além de entregar o resultado, você passa a ter um canal de contato com quem já demonstrou interesse em comprar.

Webhook: o que acontece depois do pagamento

O webhook é a parte que mais confunde, mas o conceito é simples. Enquanto o usuário está dentro do checkout, ele está no "outro mundo", o site do gateway, e você não enxerga o que ele faz lá. Quando o pagamento acontece, o gateway chama a URL que você cadastrou e conta o que houve.

Na prática, você cadastra um endpoint no seu backend e trata a notificação: se o pagamento foi confirmado, gera o áudio e envia por e-mail; se o usuário desistiu, pode disparar um lembrete. A documentação de webhooks da AbacatePay permite gerenciar esses eventos. No ambiente de teste, o botão de simular pagamento já aciona o webhook, o que acelera muito o desenvolvimento.

Daniel recomenda não confiar apenas no redirect da completedUrl: use o webhook como fonte de verdade e faça a dupla verificação no backend antes de liberar o produto.

Implementação no backend e no frontend

O backend do exemplo usa Fastify sobre Node.js, e o frontend usa Next.js, no ecossistema React. Como tudo se resume a um POST HTTP, a stack não importa: você pode pegar o exemplo da documentação e pedir a qualquer assistente de código para converter para Java, Ruby, C# ou o que você usar.

A rota createIntent segue esta sequência:

1. Recebe os dados do formulário (nome, e-mail, mensagem).
2. Gera um externalId único, por exemplo com uid.
3. Monta o POST para a AbacatePay com o token no header, os produtos, a returnUrl e a completedUrl.
4. Lê o response, converte para JSON e extrai data.url.
5. Devolve essa URL ao frontend, que redireciona o usuário para o checkout.

Como a lógica de geração do produto (o áudio) depende da confirmação do pagamento, o gatilho correto é o webhook, não o clique. O clique só cria a intenção de compra; o PIX caindo na sua conta é que libera a entrega.

Perguntas frequentes

• Preciso saber JavaScript para integrar PIX? Não. A integração é um POST HTTP com JSON, então qualquer linguagem serve. O vídeo usa Fastify no backend e Next.js no frontend, mas o fluxo é o mesmo em Java, Ruby ou C#.

• O preço na API é em reais ou centavos? Em centavos. Para cobrar R$ 5,00, envie 500 no campo price. O mínimo aceito é 100, equivalente a R$ 1,00.

• Posso testar sem pagar de verdade? Sim. A AbacatePay oferece um botão de simular pagamento no checkout de teste, que dispara o webhook normalmente. Você valida todo o fluxo sem transferir dinheiro.

• Qual a diferença entre returnUrl e completedUrl? A returnUrl recebe o usuário que clicou em voltar dentro do checkout. A completedUrl recebe quem terminou o pagamento. As duas apontam para o seu site.

• Posso confiar só no redirect de retorno? Não é recomendado. O redirect depende do navegador do usuário. Use o webhook como confirmação oficial e faça uma dupla verificação no backend antes de entregar o produto.

• A AbacatePay aceita assinaturas recorrentes? No momento da gravação, em janeiro de 2025, havia apenas cobranças one-time via PIX. Consulte a documentação atual, porque recursos de recorrência podem ter sido adicionados desde então.

• Preciso criar um cliente antes da cobrança? Não necessariamente. Você pode criar a cobrança direto e passar os dados do customer; se o cliente não existir, a API o cria. Criar cliente separado faz sentido em cenários de recorrência ou marketing.

• O que colocar no externalId? Um identificador único do item no seu sistema, como o ID do pedido ou da sessão. Ele volta nas notificações e no redirect, permitindo amarrar o pagamento ao produto certo.

• Gateway de pagamento custa caro? Depende do provedor. A AbacatePay cobrava R$ 0,80 por transação na época do vídeo, uma das taxas mais baixas citadas, mas compare com alternativas como Stripe e Mercado Pago antes de decidir.

Onde aprender mais e transformar vídeo em artigo

O vídeo faz parte da jornada do criador no Crazystack Typescript, a comunidade do Gustavo Dev Doido, onde ele construiu o SaaS do zero no Bootcamp do Dev Doido, do design no Figma ao deploy. Se o seu conhecimento também está preso em vídeos longos, a mesma lógica do webhook se aplica ao conteúdo: a informação existe, falta apenas entregá-la no formato certo.

É exatamente isso que o Skala Blog faz. Você cola a URL de um vídeo do YouTube, a plataforma transcreve e gera um artigo estruturado, pronto para revisão e publicação. Vale para aulas, entrevistas, tutoriais e opiniões que merecem vida além do player.

Source video