API PIX: como gerar cobranças com QR Code e validar webhooks, passo a passo
Integrar PIX por API é o caminho para quem tem checkout próprio, SaaS ou sistema interno. Este guia mostra o fluxo completo com a API v3 da ZuckPay, mas as boas práticas valem para qualquer provedor.
Neste artigo 11 seções
- O fluxo em 5 passos
- Antes de começar
- Passo 1: autenticação
- Passo 2: criar a cobrança PIX
- Passo 3: mostrar o QR Code
- Passo 4: receber e validar o webhook
- Passo 5: liberar o produto com segurança
- Além do PIX: cartão, cripto e internacional
- Integração por IA com MCP
- Checklist antes de ir para produção
- Perguntas frequentes
O fluxo em 5 passos
- Pegue o
client_ide oclient_secretno painel. - Crie a cobrança com
POST /conta/v3/pix/qrcode. - Mostre o QR Code e o copia-e-cola para o comprador.
- Receba o webhook de pagamento e valide a assinatura.
- Libere o produto só depois do webhook validado.
Antes de começar
Você vai precisar de uma conta ZuckPay aprovada e das credenciais de API. No painel, abra Credenciais API e copie o client_id e o client_secret. Gere também um Webhook Secret: ele é usado para assinar as notificações.
client_secret e o Webhook Secret ficam só no servidor, em variáveis de ambiente. Nunca coloque essas chaves no JavaScript do navegador, no app do celular ou no repositório.
Passo 1: autenticação
A API v3 usa HTTP Basic Auth: o client_id é o usuário e o client_secret é a senha. O cabeçalho fica assim:
Authorization: Basic base64(SEU_CLIENT_ID:SEU_CLIENT_SECRET)
A maioria das bibliotecas HTTP monta esse cabeçalho sozinha: no cURL é a opção -u.
Passo 2: criar a cobrança PIX
Envie o valor e os dados do pagador para o endpoint de QR Code:
curl -X POST https://www.zuckpay.com.br/conta/v3/pix/qrcode \
-u "SEU_CLIENT_ID:SEU_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{"valor": 97.00, "nome": "Cliente Teste", "cpf": "00000000000", "email": "[email protected]", "telefone": "11999998888"}'
A resposta traz o transactionId, o código PIX copia-e-cola e a imagem do QR Code pronta para exibir. Guarde o transactionId junto do pedido no seu banco de dados: é ele que liga o pagamento ao pedido quando o webhook chegar.
O mesmo pedido em PHP
<?php
$payload = [
'valor' => 97.00,
'nome' => $pedido['nome'],
'cpf' => $pedido['cpf'],
'email' => $pedido['email'],
'telefone' => $pedido['telefone'],
];
$ch = curl_init('https://www.zuckpay.com.br/conta/v3/pix/qrcode');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_USERPWD => getenv('ZP_CLIENT_ID') . ':' . getenv('ZP_CLIENT_SECRET'),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
]);
$resp = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status >= 300 || empty($resp['transactionId'])) {
// registre o erro e mostre uma mensagem amigável ao comprador
}
salvarTransacao($pedido['id'], $resp['transactionId']);
Passo 3: mostrar o QR Code
Na tela de pagamento, mostre três coisas: a imagem do QR Code para quem está no computador, o botão de copiar o código copia-e-cola para quem está no celular, e o valor em destaque. Boas práticas que aumentam a conversão:
- No celular, coloque o botão "Copiar código PIX" acima do QR Code: é o que a maioria usa.
- Mostre um aviso de "aguardando pagamento" que muda sozinho quando o pagamento for confirmado. Para isso, consulte o status do pedido no seu servidor, que é atualizado pelo webhook.
- Mande o código também por e-mail ou WhatsApp, para recuperar quem saiu da página sem pagar.
Passo 4: receber e validar o webhook
Quando o pagamento é confirmado, a ZuckPay envia uma notificação para a URL de webhook cadastrada. Com o Webhook Secret gerado, toda notificação vem com o cabeçalho X-ZuckPay-Signature, no formato t=<timestamp>,v1=<hash>. Para validar:
- Leia o corpo cru da requisição, antes de qualquer conversão de JSON.
- Separe o
t(timestamp) e ov1(assinatura) do cabeçalho. - Recuse se o timestamp tiver mais de 5 minutos: isso bloqueia reenvio de notificações antigas.
- Calcule
HMAC-SHA256(t + "." + corpo, webhook_secret)e compare com ov1usando comparação de tempo constante.
Validação em PHP
<?php
$body = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_ZUCKPAY_SIGNATURE'] ?? ''; // "t=<ts>,v1=<hex>"
$secret = getenv('ZP_WEBHOOK_SECRET');
parse_str(strtr($sig, ',', '&'), $parts);
$ts = $parts['t'] ?? '';
$v1 = $parts['v1'] ?? '';
if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; } // anti-replay
$expected = hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($expected, $v1)) { http_response_code(401); exit; }
$evento = json_decode($body, true);
// atualize o pedido pelo transactionId e libere o acesso
http_response_code(200);
Validação em Node.js (Express)
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/webhook/zuckpay', express.raw({ type: '*/*' }), (req, res) => {
const body = req.body.toString('utf8'); // corpo cru
const sig = req.get('X-ZuckPay-Signature') || '';
const parts = Object.fromEntries(sig.split(',').map(p => p.split('=')));
const ts = Number(parts.t);
if (!ts || Math.abs(Date.now() / 1000 - ts) > 300) return res.sendStatus(400);
const expected = crypto.createHmac('sha256', process.env.ZP_WEBHOOK_SECRET)
.update(`${parts.t}.${body}`).digest('hex');
const ok = parts.v1 && expected.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
if (!ok) return res.sendStatus(401);
const evento = JSON.parse(body);
// atualize o pedido pelo transactionId e libere o acesso
res.sendStatus(200);
});
Passo 5: liberar o produto com segurança
- Libere só depois do webhook validado. Nunca confie em um aviso de "paguei" vindo do navegador.
- Torne o processamento idempotente. O mesmo webhook pode chegar mais de uma vez. Antes de liberar, verifique se aquele
transactionIdjá foi processado. - Responda rápido. Devolva
200assim que validar e salvar o evento. Trabalho pesado, como mandar e-mail ou gerar nota, vai para uma fila. - Registre tudo. Guarde o corpo do webhook e a data de recebimento: isso ajuda a defender um MED depois.
Além do PIX: cartão, cripto e internacional
A mesma API cria cobranças no cartão de crédito (com multiadquirência para aumentar a aprovação), em cripto (USDT) e em moedas internacionais (USD, EUR, INR e MXN), com métodos locais como PayPal, SPEI e MB WAY configuráveis por produto. Os detalhes estão na documentação da API.
Integração por IA com MCP
Se você usa assistentes de IA para programar ou operar, o servidor MCP oficial da ZuckPay conecta a conta a ferramentas como Claude Code, Claude Desktop e Cursor. Com ele, dá para criar cobranças PIX e consultar saldo e transações direto da conversa. O código é aberto: github.com/ZuckPay/zuckpay-mcp, e a instalação é npm install zuckpay-mcp. Veja mais em MCP para IA.
Checklist antes de ir para produção
- Credenciais em variáveis de ambiente, fora do código.
- Webhook com assinatura validada e janela de 5 minutos.
- Processamento idempotente pelo
transactionId. - Tela de pagamento testada no celular, com botão de copiar.
- Logs de criação de cobrança e de webhooks recebidos.
- Alerta para quando a taxa de erro da API subir.
Perguntas frequentes
Como a API da ZuckPay autentica as requisições?
Por HTTP Basic Auth: o client_id é o usuário e o client_secret é a senha. As credenciais ficam no painel, em Credenciais API.
Como sei que um webhook veio mesmo da ZuckPay?
Gere um Webhook Secret no painel e valide o cabeçalho X-ZuckPay-Signature, no formato t=timestamp,v1=hash, calculando HMAC-SHA256 de timestamp + "." + corpo cru com o seu secret. Recuse se não bater ou se o timestamp tiver mais de 5 minutos.
A API aceita outros meios além do PIX?
Sim. A mesma API cria cobranças no cartão (nacional e internacional), em cripto (USDT) e em moedas como USD, EUR, INR e MXN, com métodos locais configuráveis por produto.
Dá para usar a API por um assistente de IA?
Sim. O servidor MCP oficial (pacote npm zuckpay-mcp, código aberto) conecta a conta a assistentes como Claude Code, Claude Desktop e Cursor, para criar cobranças PIX e consultar saldo e transações.
Fontes
Continue lendo
Ver todos os artigosComo escolher um gateway de pagamento para produto digital: 10 critérios que mudam o seu lucro
Taxa é só o começo. Veja os 10 pontos que definem quanto dinheiro chega na sua conta e quando, com uma planilha mental para comparar qualquer plataforma em 15 minutos.
4 min de leituraLerQuanto 7 plataformas ficam de uma venda em 2026: estudo de taxas de PIX e cartão
Comparamos a taxa padrão publicada de 7 plataformas em 5 tickets, do R$ 19,90 ao R$ 497. O que cada uma fica de cada venda, quem é mais barata em cada faixa e o que a tabela não mostra.
6 min de leituraLerMED no PIX: o que é, o que mudou com o MED 2.0 e como o vendedor se defende
O Mecanismo Especial de Devolução ficou mais forte em 2026. Veja o que muda para quem vende, quais prazos valem, como evitar MED indevido e como montar a defesa com provas.
5 min de leituraLerVenda com taxa transparente
PIX com saldo no mesmo dia, cartão nacional e internacional, checkout próprio e API. Sem mensalidade: você paga quando vende.