Respostas curtas para as dúvidas mais comuns de quem integra e opera o HeroPay. Cada resposta aponta a página que explica o tema por completo.
Como pego a chave da API para testar?
A chave de teste vem do sandbox, que é gratuito e não passa por homologação. Ela autentica como Bearer em todas as requisições e deve viver só no servidor, nunca em código de cliente, app mobile ou repositório público. Se vazar, regenere no painel. Veja o passo a passo em desenvolvedores.
Qual a diferença entre sandbox e live?
Só a chave e a URL base. O sandbox roda o mesmo contrato, os mesmos endpoints e os mesmos webhooks da produção, sem dinheiro real e sem custo. Deixe a URL base e o token em variáveis de ambiente: ir para produção vira troca de duas variáveis. Detalhes em desenvolvedores.
Preciso de homologação para ir para produção?
Não. Você desenvolve e testa o fluxo inteiro no sandbox (link, checkout, webhook e estorno) e, quando estiver pronto, troca a chave e a URL base. Não há reunião comercial nem formulário de aprovação da integração. Mais em desenvolvedores.
Como valido a assinatura do webhook?
Leia o header X-HeroPay-Signature, calcule um HMAC SHA-256 do corpo bruto da requisição com o segredo do webhook e compare com uma função de tempo constante. Se não bater, responda 401 e descarte. O erro mais comum é calcular sobre o JSON já parseado e reserializado: use o corpo exatamente como chegou. Exemplos em webhooks.
Por que recebi o mesmo webhook duas vezes?
A entrega é pelo menos uma vez: se o seu endpoint demorou, respondeu erro ou a resposta se perdeu, o HeroPay tenta de novo. Deduplique por gatilho mais payment.id numa tabela com índice único antes de agir e responda 200 à segunda entrega. Mais em webhooks.
Como testo webhook no ambiente local?
Exponha o localhost com um túnel (ngrok, cloudflared ou similar) e cadastre a URL pública no sandbox. Crie um link no sandbox, pague pelo checkout de teste e veja o evento chegar. Como o sandbox é idêntico à produção, o payload é o mesmo que você vai receber no ar. Veja webhooks.
Quanto custa receber Pix?
R$ 0 por transação, em qualquer valor, inclusive cada parcela do parcelamento via Pix. Não há mensalidade, taxa de ativação nem volume mínimo, e o saque para a sua chave também não tem tarifa. Tabela completa em preços e detalhes em Pix.
Quais são os erros mais comuns ao integrar?
401 por token ausente ou sem o prefixo Bearer, esquecer o header Accept com a versão, e mandar valor em reais em vez de centavos (97 vira R$ 0,97 e gera 422). 404 indica recurso inexistente ou de outra conta. A lista completa está em desenvolvedores.
A API tem limite de requisições?
A v1 não publica um limite numérico por endpoint, mas construa como se houvesse: use webhooks em vez de polling, pagine as listagens e, ao receber 5xx ou 429, repita com backoff exponencial. Mais em desenvolvedores.