API PIX para desenvolvedores: cobrança e webhook em minutos

Gerar uma cobrança PIX

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": 100.00, "nome": "Cliente Teste", "cpf": "00000000000", "email": "[email protected]", "telefone": "11999998888"}'

A resposta traz transactionId, o QR Code (copia-e-cola) e a imagem do QR pronta para exibir no checkout.

Validar o webhook de confirmação

Cada notificação chega assinada no header X-ZuckPay-Signature, no formato t=<timestamp>,v1=<hash>. Valide antes de liberar o produto:

$body   = file_get_contents('php://input');
$sig    = $_SERVER['HTTP_X_ZUCKPAY_SIGNATURE'] ?? '';
$secret = 'SEU_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; }

O webhook secret é gerado em /conta/keys.php e é diferente do client_secret usado na autenticação.

O que mais a API v3 cobre

• Consulta de status de transação por transactionId
• Cobrança por cartão de crédito com multiadquirência automática
• Cobrança em criptomoeda (USDT) e moedas internacionais (USD, EUR, INR, MXN)
• Processamento de saque via PIX
• Split de pagamento entre múltiplos recebedores

Estabilidade em produção

A API já processou mais de 40.000 vendas, com taxa de aprovação média entre 75% e 80% — resultado da multiadquirência inteligente, que roteia cada cobrança para o adquirente com maior chance de aprovação no momento. A infraestrutura é otimizada para alta volumetria, sem gargalos de performance na geração de cobrança ou na confirmação de pagamento.

Perguntas frequentes