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.

Publicado
Leitura
3 min
Neste artigo 11 seções
  1. O fluxo em 5 passos
  2. Antes de começar
  3. Passo 1: autenticação
  4. Passo 2: criar a cobrança PIX
  5. Passo 3: mostrar o QR Code
  6. Passo 4: receber e validar o webhook
  7. Passo 5: liberar o produto com segurança
  8. Além do PIX: cartão, cripto e internacional
  9. Integração por IA com MCP
  10. Checklist antes de ir para produção
  11. Perguntas frequentes

O fluxo em 5 passos

  1. Pegue o client_id e o client_secret no painel.
  2. Crie a cobrança com POST /conta/v3/pix/qrcode.
  3. Mostre o QR Code e o copia-e-cola para o comprador.
  4. Receba o webhook de pagamento e valide a assinatura.
  5. 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.

Segurança O 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:

  1. Leia o corpo cru da requisição, antes de qualquer conversão de JSON.
  2. Separe o t (timestamp) e o v1 (assinatura) do cabeçalho.
  3. Recuse se o timestamp tiver mais de 5 minutos: isso bloqueia reenvio de notificações antigas.
  4. Calcule HMAC-SHA256(t + "." + corpo, webhook_secret) e compare com o v1 usando 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 transactionId já foi processado.
  • Responda rápido. Devolva 200 assim 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

  1. Documentação da API ZuckPay
  2. Servidor MCP oficial da ZuckPay (GitHub)
  3. Pacote zuckpay-mcp no npm
  4. Banco Central: Pix
Escrito por Cadu Bezerra

Fundador da ZuckPay. Escreve sobre pagamentos, taxas e operação de negócios digitais, com dados públicos e a experiência de quem processa vendas todos os dias.

Continue lendo

Ver todos os artigos

Venda 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.