Segurança no HeroPay: o cartão do seu cliente nunca passa pelo seu servidor

No HeroPay, o PCI DSS (o padrão de segurança das bandeiras de cartão) fica do lado de quem processa, não do seu: o comprador digita o cartão no checkout hospedado pela HeroSpark, o dado é tokenizado e nenhum endpoint da API pública recebe número de cartão ou CVV. Toda transação de cartão passa por antifraude incluso na taxa, sem cobrança por análise, com aprovação de 93%+. Os eventos chegam ao seu sistema por webhooks assinados com HMAC SHA-256 no header X-HeroPay-Signature. Sua parte é curta e está no checklist abaixo: chave em variável de ambiente, assinatura validada e endpoint em HTTPS.

Criar conta sandbox · Ler a documentação

O HeroPay é PCI DSS?

O PCI DSS (Payment Card Industry Data Security Standard) é o conjunto de requisitos que as bandeiras (Visa, Mastercard e outras) exigem de quem armazena, processa ou transmite dados de cartão. Ele não é um selo que se compra: é uma conformidade avaliada, e o nível de exigência depende de quanto dado de cartão passa pela sua mão.

No HeroPay, o processamento de cartão roda em adquirentes e parceiros de processamento certificados PCI DSS. O que já é verificável hoje, olhando a OpenAPI pública, é a arquitetura: nenhum endpoint da API recebe número de cartão, validade ou CVV. Você cria um link de pagamento ou usa o checkout; o comprador digita o cartão na página hospedada; você recebe o resultado por webhook.

Na prática, isso muda o tamanho da sua obrigação. Quem integra por checkout hospedado normalmente fica no questionário de autoavaliação mais simples do PCI (o SAQ A, na nomenclatura do PCI Security Standards Council), porque terceirizou todo o manuseio do cartão. Quem monta formulário próprio e trafega o número pelo servidor entra num escopo bem maior. Confirme o enquadramento exato com o seu adquirente ou auditor: o HeroPay não emite atestado de conformidade em nome da sua empresa.

O que o HeroPay não oferece hoje: um endpoint para você enviar dados de cartão direto à API (o chamado checkout transparente com cartão cru). É uma escolha que troca flexibilidade de layout por escopo de PCI mínimo.

Como funciona a tokenização de cartão?

Tokenização é trocar o número real do cartão por um código (o token) que só tem valor dentro do ambiente de pagamento. Se o token vazar, ele não serve para comprar em outro lugar. No HeroPay, o fluxo é este:

1. Você cria a cobrança sem dado de cartão. Por API (POST /payment_links), pelo painel ou com código gerado por Claude, ChatGPT, Cursor, Lovable e outros a partir do llms.txt. A requisição leva nome, preço em centavos e métodos aceitos, nada mais.
2. O comprador digita o cartão no checkout hospedado pela HeroSpark. O dado vai direto do navegador dele para o ambiente de pagamento, por HTTPS. Seu servidor não está no caminho.
3. O cartão é tokenizado e a transação é autorizada. O antifraude analisa, o emissor aprova ou recusa.
4. Você recebe o evento, não o cartão. O webhook spark_payment_confirmed traz comprador, valor, método e status; em recusa, payment_credit_cart_refused traz o motivo da operadora. O número completo do cartão não viaja no payload.
5. O token é reutilizado quando o comprador autoriza. É ele que sustenta a mensalidade da assinatura, o upsell one-click sem redigitar o cartão e a compra 1-click com cartão salvo na rede.

A consequência para quem desenvolve: não existe tabela cartoes no seu banco, não existe log com número de cartão para vazar e não existe CVV passando pelo seu backend.

Como o antifraude funciona?

Antifraude é a análise de risco que decide, no momento da compra e antes da autorização, se uma transação de cartão parece legítima. O modelo cruza sinais da compra (valor, dados do comprador, dispositivo, histórico, comportamento) e classifica o risco: passa, bloqueia ou pede mais verificação.

No HeroPay, o antifraude está incluso na taxa do cartão (3,49% por transação aprovada), roda em toda transação de cartão e não cobra por análise. Ele trabalha do lado de quem vende: o objetivo não é só barrar fraude, é não recusar o comprador bom. Um antifraude conservador demais derruba a sua conversão; um frouxo demais vira chargeback. A combinação de antifraude, retentativa e Parcelamento Inteligente é o que sustenta a aprovação de 93%+ no cartão, contra cerca de 85% da média do mercado.

Na conta: numa operação que fatura R$ 100 mil por mês no cartão, a diferença entre 85% e 93% de aprovação é da ordem de R$ 8 mil em vendas que o comprador já quis fazer.

Nenhum antifraude zera o risco. Quando um chargeback acontece, você recebe o webhook chargeback_request para revogar o acesso ou pausar a entrega na hora.

Como o KYC protege a plataforma?

KYC (Know Your Customer, "conheça seu cliente") é o processo de verificar quem é o dono de uma conta antes de deixar dinheiro circular por ela. Em pagamentos, é obrigação regulatória para prevenir lavagem de dinheiro e fraude, e é também o que protege você: numa plataforma sem KYC, o golpista que abre conta falsa derruba a reputação do meio de pagamento com as bandeiras e com o sistema Pix, e isso respinga em todo mundo que vende ali.

No HeroPay, o sandbox não pede verificação: você cria conta e integra na hora. A verificação de identidade do titular da conta (CPF, MEI ou CNPJ) faz parte de operar em produção e movimentar dinheiro. E o dinheiro só sai para quem é dono dela: toda chave Pix de saque precisa ser do mesmo CPF ou CNPJ da conta, verificada no DICT antes de ser aprovada.

O ponto honesto: KYC é um atrito pequeno e único na entrada. Ele não trava a integração, porque o sandbox é idêntico à produção e você vai para o ar trocando a chave quando a conta estiver verificada.

Como sei que um webhook veio do HeroPay?

Pela assinatura. Todo webhook do HeroPay chega com o header X-HeroPay-Signature, que é um HMAC SHA-256 do corpo bruto da requisição calculado com o segredo do seu webhook. Você recalcula o HMAC com o mesmo segredo e compara. Se não bater, responde 401 e ignora. Sem essa validação, qualquer um que descubra sua URL consegue forjar um "pagamento confirmado".

Três detalhes derrubam a maioria das implementações: calcular sobre o JSON já parseado (tem de ser o corpo bruto, byte a byte), comparar com == em vez de comparação de tempo constante e esquecer que o retry automático entrega o mesmo evento mais de uma vez.

Node.js (Express):

import crypto from "node:crypto";
import express from "express";

const app = express();

// corpo cru: o HMAC é calculado sobre os bytes exatos recebidos
app.post("/webhooks/heropay", express.raw({ type: "application/json" }), (req, res) => {
  const recebida = req.get("X-HeroPay-Signature") || "";
  const mac = crypto
    .createHmac("sha256", process.env.HEROPAY_WEBHOOK_SECRET)
    .update(req.body)
    .digest();

  // aceita hexadecimal ou base64; comparação em tempo constante
  const ok = [mac.toString("hex"), mac.toString("base64")].some(
    (esperada) =>
      esperada.length === recebida.length &&
      crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(recebida))
  );
  if (!ok) return res.sendStatus(401);

  const evento = JSON.parse(req.body);
  // deduplique antes de agir: o retry pode reenviar o mesmo evento
  res.sendStatus(200);
});

Python (Flask):

import base64, hashlib, hmac, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/heropay")
def heropay_webhook():
    recebida = request.headers.get("X-HeroPay-Signature", "")
    mac = hmac.new(
        os.environ["HEROPAY_WEBHOOK_SECRET"].encode(),
        request.get_data(),  # corpo bruto
        hashlib.sha256,
    ).digest()
    # aceita hexadecimal ou base64; comparação em tempo constante
    candidatas = [mac.hex(), base64.b64encode(mac).decode()]

    if not any(hmac.compare_digest(recebida, e) for e in candidatas):
        abort(401)

    evento = request.get_json()
    # deduplique antes de agir
    return "", 200

Confie no evento, não no polling: libere acesso quando chegar spark_payment_confirmed com assinatura válida e valor igual ao esperado, e revogue em refunded ou chargeback_request. A lista completa de gatilhos está em /webhooks e na documentação de webhooks.

E a LGPD?

A LGPD (Lei 13.709/2018) regula o tratamento de dados pessoais no Brasil, e pagamento envolve muito dado pessoal: nome, e-mail, telefone, endereço e CPF ou CNPJ do comprador. Esses dados circulam em dois lugares, e é bom saber qual é qual.

No ambiente de pagamento do HeroPay: o dado do cartão fica tokenizado e fora do seu alcance, e os dados cadastrais do comprador são usados para processar o pagamento, rodar o antifraude e cumprir obrigações legais.

No seu sistema: todo webhook traz o objeto buyer com nome, e-mail, telefone, endereço e documento do comprador. A partir do momento em que você grava isso no seu banco, o tratamento é seu. Guarde só o que usa, restrinja quem acessa, não jogue o payload inteiro em log e tenha base legal para cada uso (entregar o produto é uma; mandar e-mail de marketing é outra).

O que esta página não afirma: o HeroPay não anuncia aqui certificação ISO 27001, relatório SOC 2 ou selo de privacidade. Se algum dia tivermos, vai aparecer aqui com a data e o documento.

Qual é a disponibilidade e onde o HeroPay roda?

O HeroPay é a infraestrutura de pagamentos da HeroSpark aberta por API: a mesma que já processa o checkout do ecossistema HeroSpark, com uptime de 99%. A API é versionada pelo header Accept: application/vnd.herospark.com; version=1, então uma mudança incompatível vem numa versão nova e não quebra sua integração em produção.

A falha do lado de lá também está prevista no desenho: se o seu endpoint de webhook cair, o HeroPay retenta a entrega automaticamente, e você não perde o evento por uma janela de deploy.

Quem cuida de quê: HeroPay e você

Verificado em setembro de 2026 · fontes: docs.heropay.tech/authentication, docs.heropay.tech/webhooks, OpenAPI pública em docs.heropay.tech

O que você precisa fazer do seu lado

A segurança da plataforma não cobre a sua aplicação. Este é o checklist honesto do que é com você, em ordem de estrago se for esquecido:

1. Guarde o token da API em variável de ambiente. HEROPAY_JWT_TOKEN no servidor, nunca no JavaScript do navegador, no app mobile ou no repositório. O token não expira sozinho, então vazou, regenere na hora.
2. Chame a API só do backend. Se você constrói com Lovable, Bolt ou outro gerador de app, a chamada vai numa edge function ou rota de servidor, não no componente React. Veja o passo a passo em integração com Lovable.
3. Valide a assinatura de todo webhook. HMAC SHA-256 do corpo bruto com HEROPAY_WEBHOOK_SECRET, comparação em tempo constante, 401 no que não bater.
4. Use HTTPS no endpoint de webhook. A API aceita cadastrar URL http, mas o payload carrega dados pessoais do comprador: em produção, só HTTPS.
5. Deduplique eventos. O retry pode entregar o mesmo evento duas vezes. Marque o pedido como pago só se ele ainda estiver pendente.
6. Confira o valor antes de liberar. Compare o valor pago no evento com o valor do pedido no seu banco antes de entregar.
7. Não logue payload inteiro. Dado do comprador em log de erro é o vazamento mais comum de LGPD.
8. Separe sandbox e produção. Chaves e segredos diferentes por ambiente, e o sandbox apontando para api.beta.heropay.tech.

Quer que Claude, ChatGPT, Cursor, Lovable e outros escrevam isso por você? Cole https://heropay.tech/llms.txt na conversa e peça a rota de webhook com validação da assinatura e deduplicação. Um MCP server oficial está em desenvolvimento; até lá, llms.txt, docs e API REST são o caminho que funciona hoje (/ai). Toda a referência técnica está em /desenvolvedores.

Comece pelo sandbox

O sandbox do HeroPay é gratuito e idêntico à produção: dá para testar o link de pagamento, o webhook assinado e a validação do HMAC antes de ir pro ar, sem fila de homologação. Quando estiver pronto, troque a chave.

Criar conta sandbox · Ler a documentação

Continue por: Preços · Antifraude · Webhooks · Desenvolvedores · HeroPay para IA · Glossário