Para aceitar Pix via API no HeroPay, crie um link com payment_methods: ["pix"] em POST /payment_links, envie o comprador à URL de checkout da resposta e libere o pedido no webhook spark_payment_confirmed.
O QR Code e o copia e cola são gerados pelo checkout hospedado, não por um endpoint separado: na v1 não existe chamada para criar um QR Code Pix solto, fora do link. Em troca, você não mantém tela de pagamento, e o Pix custa R$ 0 por transação e cai na hora.
Criar conta sandbox Ler a documentação
Antes de começar
- Conta sandbox e token JWT. Crie em app.heropay.tech e copie o token na seção de API. O sandbox é gratuito e roda o mesmo contrato da produção.
- Um endpoint HTTPS público para receber webhooks. Em desenvolvimento, um túnel (ngrok, cloudflared) resolve.
- Variáveis de ambiente no servidor, nunca no front-end:
export HEROPAY_API_URL="https://api.beta.heropay.tech" # sandbox
export HEROPAY_JWT_TOKEN="seu-jwt-do-sandbox"Passo a passo
1. Crie o link de pagamento só com Pix
curl -X POST "$HEROPAY_API_URL/payment_links" \
-H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
-H "Accept: application/vnd.herospark.com; version=1" \
-H "Content-Type: application/json" \
-d '{
"payment_link": {
"name": "Pedido 4821",
"description": "Consultoria avulsa de 1 hora",
"price_cents": 49700,
"absorbs_fees": true,
"payment_methods": ["pix"],
"src": "pedido-4821"
}
}'Três campos são obrigatórios na prática: name, price_cents (inteiro em centavos, mínimo 500, ou seja R$ 5,00) e absorbs_fees (true ou false). Se você não mandar payment_methods, o padrão é Pix e cartão. O src é opcional e volta em todo webhook daquela compra: use o ID do seu pedido.
Resposta 201 Created:
{
"message": "Payment link created successfully",
"data": {
"id": 136,
"name": "Pedido 4821",
"description": "Consultoria avulsa de 1 hora",
"price_cents": 49700,
"absorbs_fees": true,
"max_installments": 1,
"period": "unitary",
"frequency_type": "unlimited",
"frequency_limit": null,
"overdue_type": "none",
"overdue_limit": null,
"public_id": "fc280e25-7cbd-446f-b34f-5b8824bb5124",
"offer": {
"id": 6094,
"kind": "payment_link",
"url": "https://pay.beta.herospark.com/fc280e25-7cbd-446f-b34f-5b8824bb5124-6094?src=pedido-4821",
"accepted_payment_methods": ["pix"]
},
"created_at": "2026-09-23T10:07:01.929-03:00",
"updated_at": "2026-09-23T10:07:01.929-03:00"
}
}Grave data.id e data.offer.url junto do pedido. O POST /payment_links não é idempotente: se a chamada der timeout, consulte GET /payment_links antes de criar de novo, ou você terá dois links para o mesmo pedido.
2. Mande o comprador para o checkout
Redirecione para data.offer.url, coloque no botão "Pagar com Pix" ou envie por WhatsApp. O checkout mostra o QR Code e o copia e cola; o comprador paga no app do banco. O Pix gerado tem validade: a data de expiração vem em payment_methods.pix.expiration_at no webhook payment_pix_created, e é por ela que você agenda um lembrete.
3. Cadastre os webhooks e confirme o pagamento
Um cadastro por gatilho. Para Pix, dois interessam:
curl -X POST "$HEROPAY_API_URL/webhook" \
-H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
-H "Accept: application/vnd.herospark.com; version=1" \
-H "Content-Type: application/json" \
-d '{
"webhook": {
"trigger": "spark_payment_confirmed",
"webhook_url": "https://seuapp.com/webhooks/heropay",
"request_method": "post"
}
}'Repita com "trigger": "payment_pix_created" se quiser saber quando o comprador gerou o Pix (útil para lembrete antes de expirar). A resposta 201 traz "message": "Webhook created successfully" e o data.id do webhook.
Quando o Pix cai, sua URL recebe um POST com o template padrão. Recorte dos campos que o handler usa (valores ilustrativos, campos reais do template; o payload completo está na documentação de webhooks):
{
"payment": {
"id": "8812345",
"method": "pix",
"net_value_cents": "49700"
},
"cart": { "src": "pedido-4821" },
"payment_methods": {
"pix": { "expiration_at": "2026-09-23T10:42:44-03:00" }
}
}Valide o header X-HeroPay-Signature (HMAC SHA-256 do corpo bruto), localize o pedido por cart.src, deduplique por payment.id + gatilho e só então libere. O próprio gatilho spark_payment_confirmed já significa pagamento confirmado: decida pelo gatilho, não pelo texto de campos de status. Confie no evento, não no polling. Mais sobre a validação em /webhooks.
Variações
Por prompt, com o llms.txt
Cole https://heropay.tech/llms.txt no Claude, ChatGPT, Cursor, Lovable e outros (mais em /ai) e peça:
Cria um link de pagamento de R$ 497 só com Pix, nome "Pedido 4821",
src "pedido-4821", e cadastra um webhook de pagamento confirmado
para https://seuapp.com/webhooks/heropay.Com o contrato da API no contexto, a IA monta o POST /payment_links e o POST /webhook com os campos certos (inclusive 49700 em centavos). Revise as chamadas antes de rodar. Um MCP server oficial está em desenvolvimento.
Sem código, pelo painel
Em app.heropay.tech, crie o link de pagamento marcando só Pix, copie a URL e envie ao comprador.
Erros comuns e como ler a mensagem
| Status | Mensagem (real) | Causa e correção |
|---|---|---|
401 | corpo com error | Token ausente, sem o prefixo Bearer ou de outro ambiente (token de sandbox na URL de produção). |
422 | Price cents must be greater than or equal to 500 | Valor abaixo de R$ 5,00, quase sempre por mandar reais em vez de centavos (497 em vez de 49700). |
422 | Absorbs fees is not included in the list | absorbs_fees ausente ou como texto. Mande true ou false. |
422 | Src is invalid | src com espaço, acento ou /. Aceita letras, números e . _ - ~, até 255 caracteres. |
422 (webhook) | Trigger is not included in the list | Gatilho digitado errado. A lista válida está em /webhooks. |
404 | Payment link not found | ID inexistente ou de outra conta. |
A API junta vários erros de validação numa só string separada por vírgula, por exemplo Absorbs fees is not included in the list, Price cents must be greater than or equal to 500. Leia inteira antes de corrigir um campo por vez.
Perguntas frequentes
Existe endpoint para gerar QR Code Pix direto pela API?
Não na v1. O Pix para o comprador sempre nasce do link de pagamento: você cria o link com payment_methods: ["pix"] e o checkout hospedado gera o QR Code e o copia e cola. Isso é diferente de provedores que expõem um POST /cob no padrão do Banco Central. A vantagem é que você não constrói tela nem trata expiração do QR; a limitação é que o comprador passa pelo checkout do HeroPay. Os endpoints /financial/pix_accounts existem, mas servem para cadastrar as suas chaves de recebimento e saque, não para cobrar.
Quanto custa receber Pix via API?
R$ 0 por transação de Pix pago, sem mensalidade, sem ativação e sem mínimo. Numa venda de R$ 497, entram R$ 497 no saldo. A API não cobra por chamada. Cartão, para comparação, custa 3,49% por transação aprovada. Tabela completa em /precos.
Como sei que o Pix foi pago sem ficar consultando a API?
Pelo webhook spark_payment_confirmed, que chega na URL que você cadastrou com POST /webhook assim que o pagamento é confirmado. Ele traz cart.src (o ID do pedido que você mandou no link) e payment.net_value_cents. Valide a assinatura X-HeroPay-Signature antes de agir e deduplique, porque a retentativa pode entregar o mesmo evento duas vezes. Polling em GET /transactions/by_status fica como rede de segurança, não como mecanismo principal.
Dá para oferecer Pix e cartão no mesmo link?
Sim. Mande "payment_methods": ["pix", "credit_card"] (é o padrão quando o campo não vai) ou inclua "bank_slip" para boleto. O comprador escolhe no checkout. Uma boa prática é deixar Pix e cartão juntos: se o cartão for recusado, o Pix vira a saída na mesma tela, sem novo link. Para parcelar o cartão, use max_installments de 1 a 12, com parcela mínima de R$ 1,99.
Posso testar o Pix no sandbox sem dinheiro real?
Sim. O sandbox em https://api.beta.heropay.tech é gratuito, não passa por homologação e dispara os mesmos webhooks da produção. Crie o link, abra o checkout de teste e gere o Pix para ver payment_pix_created chegar no seu endpoint. Para inspecionar o payload sem escrever código, aponte o webhook para um serviço como webhook.site.
Como ligo o Pix ao pedido do meu sistema?
Pelo src. Mande o ID do pedido em src ao criar o link (por exemplo pedido-4821); ele é concatenado na URL do checkout e volta em cart.src em todos os webhooks daquela compra. No seu handler, busque o pedido por esse valor. Se você reutiliza o mesmo link para vários compradores, o src identifica a campanha, não o pedido: nesse caso use payment.id como chave da transação. O passo a passo de conciliação está em /como/automatizar-conciliacao.