Integre pagamentos pelo Claude Code em minutos: Pix a R$ 0 direto do terminal

Para integrar pagamentos pelo Claude Code, você aponta heropay.tech/llms.txt e a documentação em docs.heropay.tech no CLAUDE.md do projeto e manda um prompt em português com o contrato da API. O Claude Code escreve no seu próprio repositório a rota que chama POST /payment_links, a tabela de pedidos e o webhook com validação HMAC, na stack que você já usa. Você testa com curl no sandbox, cadastra o webhook, troca a chave e vá pro ar. Pix a R$ 0, boleto a R$ 0 e cartão em até 12x.

Criar conta sandbox · Ler a documentação

Como integrar pagamentos pelo Claude Code com o HeroPay?

São sete passos. Os quatro primeiros deixam o código escrito; o resto depende de quanto você quer testar antes de ir ao ar.

# .env (nunca versionado)
HEROPAY_API_URL=https://api.beta.heropay.tech
HEROPAY_API_KEY=seu-jwt-do-sandbox
HEROPAY_WEBHOOK_SECRET=segredo-de-assinatura-do-webhook

set -a; source .env; set +a

curl -s -X POST "$HEROPAY_API_URL/payment_links" \
  -H "Authorization: Bearer $HEROPAY_API_KEY" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -H "Content-Type: application/json" \
  -d '{"payment_link":{"name":"Teste Claude Code","description":"Link de teste","price_cents":500,"absorbs_fees":false,"max_installments":1,"payment_methods":["pix","credit_card","bank_slip"],"src":"teste-local"}}'

## Pagamentos (HeroPay)

- Referência: https://heropay.tech/llms.txt (visão geral) e https://docs.heropay.tech (referência da API). Não invente endpoint nem campo que não esteja na documentação.
- Base: HEROPAY_API_URL (sandbox https://api.beta.heropay.tech, produção https://api.heropay.tech).
- Toda chamada leva: Authorization: Bearer $HEROPAY_API_KEY e Accept: application/vnd.herospark.com; version=1.
- A chave só é lida no servidor, via variável de ambiente. Nunca em código de cliente, em log ou em commit.
- Dinheiro é inteiro em centavos (price_cents: 19700 = R$ 197,00). Mínimo de um link: 500. Parcelas de 1 a 12, mínimo R$ 1,99 por parcela.
- O preço sai do servidor. O cliente manda só o identificador do produto.
- Pagamento se confirma pelo webhook spark_payment_confirmed, nunca pelo redirect do checkout.
- Webhook: validar X-HeroPay-Signature (HMAC SHA-256 do corpo bruto com HEROPAY_WEBHOOK_SECRET) antes de parsear o JSON; comparar em tempo constante; deduplicar por pagamento + gatilho.
- O campo src do link volta em cart.src em todo webhook: use o id do pedido.
- Testes contra a API só com a chave de sandbox. Pergunte antes de cadastrar webhook ou de chamar qualquer endpoint que não seja de leitura.

Quero aceitar pagamentos neste projeto usando a API HeroPay. Siga as regras da seção "Pagamentos (HeroPay)" do CLAUDE.md. Use https://heropay.tech/llms.txt como visão geral e https://docs.heropay.tech como referência da API. Não invente endpoints nem campos.

CONTEXTO DO PRODUTO
- O que vendo: [ex.: "Plano Pro anual do meu SaaS de agendamento"]
- Identificador: [ex.: plano-pro-anual]
- Preço: [ex.: R$ 197,00]
- Parcelamento no cartão: até [12]x
- Métodos: Pix, cartão e boleto

0. ANTES DE ESCREVER CÓDIGO
- Leia o projeto e me diga a stack, o ORM, onde ficam as rotas de servidor e como os testes rodam. Siga os padrões que já existem aqui; não adicione framework novo.
- Rode (com a minha aprovação) um curl de POST {HEROPAY_API_URL}/payment_links no sandbox criando um link de teste de R$ 5,00 (price_cents 500), lendo a chave de $HEROPAY_API_KEY, e me mostre a resposta. Use essa resposta real para confirmar os nomes dos campos (data.id, data.offer.url).
- Me mostre o plano de arquivos antes de alterar qualquer coisa.

1. CONFIGURAÇÃO
- Crie um módulo de configuração que lê HEROPAY_API_URL, HEROPAY_API_KEY e HEROPAY_WEBHOOK_SECRET do ambiente e falha na inicialização se faltar alguma.
- Adicione as três ao .env.example com valores de exemplo, nunca reais. Confirme que .env está no .gitignore.
- A chave nunca aparece em código de cliente, em variável com prefixo público (NEXT_PUBLIC_, VITE_, EXPO_PUBLIC_), em log ou em mensagem de erro.

2. BANCO DE DADOS (migration no ORM do projeto)
- Tabela products: key (único), name, description, price_cents (inteiro). Cadastre o produto acima numa seed.
- Tabela orders: id, user_id, product_key, amount_cents (inteiro), status (pending, paid, refunded, canceled; padrão pending), checkout_url, heropay_payment_link_id, paid_at (nulo), created_at.
- Tabela heropay_events: payment_id, trigger, received_at, com índice único em (payment_id, trigger). É o registro de idempotência.

3. ROTA POST /api/checkout (servidor)
- Exige usuário autenticado. Recebe só product_key. Recuse qualquer preço vindo do cliente.
- Busca o preço em products, cria o pedido pending e chama POST {HEROPAY_API_URL}/payment_links com os headers:
  Authorization: Bearer {HEROPAY_API_KEY}
  Accept: application/vnd.herospark.com; version=1
  Content-Type: application/json
- Corpo:
  {
    "payment_link": {
      "name": "<nome do produto>",
      "description": "<descrição do produto>",
      "price_cents": <inteiro em centavos, mínimo 500>,
      "absorbs_fees": false,
      "max_installments": [12],
      "payment_methods": ["pix", "credit_card", "bank_slip"],
      "src": "<id do pedido>"
    }
  }
- absorbs_fees false repassa os juros do parcelamento ao comprador; true faz eu absorver para vender sem juros. O src aceita só letras, números e . _ - ~.
- Salve data.id em heropay_payment_link_id e data.offer.url em checkout_url. Devolva ao cliente só checkout_url e o id do pedido.
- Timeout de 10 segundos. Não repita a chamada automaticamente: POST /payment_links não é idempotente e cria um link novo a cada chamada. Em erro da API, registre status e corpo no log (sem headers) e devolva mensagem amigável.

4. ROTA POST /api/webhooks/heropay/:trigger (servidor, pública)
- Cada gatilho será cadastrado com a própria URL: /api/webhooks/heropay/<gatilho>. Leia o gatilho do caminho.
- Leia o corpo BRUTO antes de qualquer parser de JSON. Calcule HMAC SHA-256 do corpo bruto com HEROPAY_WEBHOOK_SECRET e compare com o header X-HeroPay-Signature em tempo constante, checando o tamanho antes. Confira na documentação de webhooks o formato da assinatura (hex ou base64); se não estiver claro, aceite os dois e me avise. Se não bater ou faltar o header, responda 401 sem processar.
- Só depois parseie o JSON. O id do pedido vem em cart.src; o id do pagamento vem no objeto payment (confirme o nome do campo na documentação).
- Idempotência: insira (payment_id, trigger) em heropay_events; se já existir, responda 200 e não faça mais nada.
- spark_payment_confirmed: marque o pedido como paid e grave paid_at, só se ele estiver pending e se o valor pago bater com amount_cents (confira na documentação o campo de valor e se ele vem em reais ou em centavos). Se não bater, registre no log e não libere.
- refunded e chargeback_request: marque como refunded e revogue o acesso.
- cart.src desconhecido: registre no log e responda 200.
- Responda 2xx rápido. Trabalho pesado (e-mail, provisionamento) vai para a fila que o projeto já usa; se não houver fila, faça depois de gravar o status.
- Em ambiente de desenvolvimento, salve o corpo bruto do primeiro evento de cada gatilho em test/fixtures/heropay/<gatilho>.json (sem dados reais de produção).

5. CLIENTE
- Botão "Comprar" chama /api/checkout e redireciona para checkout_url.
- Página /pedido/:id mostra "Aguardando pagamento" enquanto status = pending e consulta o próprio backend a cada 5 segundos. Com status = paid, mostra "Pagamento confirmado".
- Nunca libere acesso porque o comprador voltou do checkout. Quem libera é o status paid gravado pelo webhook.

6. TESTES (no framework de testes do projeto)
- Assinatura válida responde 200; inválida ou ausente responde 401 e não altera nada.
- O mesmo evento enviado duas vezes marca o pedido como pago uma vez só.
- /api/checkout ignora preço enviado pelo cliente.
- Nenhum teste chama a API real: faça mock do cliente HTTP.

7. ENTREGA
- Rode o linter e os testes e me mostre o resultado.
- Me dê os comandos curl para: criar um pedido local, simular webhook com assinatura inválida e reenviar uma fixture assinada.
- NÃO cadastre webhook sem me perguntar. Não crie nada fora do que foi pedido.

# 1. Cria um pedido (use a sessão de um usuário de desenvolvimento)
curl -s -X POST http://localhost:3000/api/checkout \
  -H "Content-Type: application/json" \
  -H "Cookie: <sessão do usuário de dev>" \
  -d '{"product_key":"plano-pro-anual"}'

# 2. Webhook forjado: tem que responder 401 e não mudar nada
curl -s -o /dev/null -w "%{http_code}\n" -X POST \
  "http://localhost:3000/api/webhooks/heropay/spark_payment_confirmed" \
  -H "Content-Type: application/json" \
  -H "X-HeroPay-Signature: assinatura-falsa" \
  -d '{"cart":{"src":"qualquer-coisa"}}'

cloudflared tunnel --url http://localhost:3000
# devolve algo como https://abc-123.trycloudflare.com

TUNEL="https://abc-123.trycloudflare.com"
for trigger in spark_payment_confirmed refunded chargeback_request; do
  curl -s -X POST "$HEROPAY_API_URL/webhook" \
    -H "Authorization: Bearer $HEROPAY_API_KEY" \
    -H "Accept: application/vnd.herospark.com; version=1" \
    -H "Content-Type: application/json" \
    -d "{\"webhook\":{\"trigger\":\"$trigger\",\"webhook_url\":\"$TUNEL/api/webhooks/heropay/$trigger\",\"request_method\":\"post\"}}"
done

F=test/fixtures/heropay/spark_payment_confirmed.json
SIG=$(openssl dgst -sha256 -hmac "$HEROPAY_WEBHOOK_SECRET" "$F" | awk '{print $NF}')
curl -s -w "\n%{http_code}\n" -X POST \
  "http://localhost:3000/api/webhooks/heropay/spark_payment_confirmed" \
  -H "Content-Type: application/json" \
  -H "X-HeroPay-Signature: $SIG" \
  --data-binary @"$F"

O que o Claude Code vai gerar no seu repositório?

Com o prompt acima, o Claude Code monta cinco peças, na stack que já existe no projeto. Revise cada uma antes do merge.

A validação do webhook é a parte que mais vale revisar. Em Node, ela fica parecida com isto (Next.js App Router, que entrega o corpo bruto com req.text()):

// app/api/webhooks/heropay/[trigger]/route.ts
import crypto from "node:crypto";

function assinaturaValida(raw: string, recebida: string, segredo: string) {
  const hmac = () => crypto.createHmac("sha256", segredo).update(raw);
  // confira o formato (hex ou base64) na documentação de webhooks e mantenha só o certo
  const esperadas = [hmac().digest("hex"), hmac().digest("base64")];
  const r = Buffer.from(recebida);
  return esperadas.some((e) => {
    const b = Buffer.from(e);
    return r.length === b.length && crypto.timingSafeEqual(r, b);
  });
}

export async function POST(
  req: Request,
  { params }: { params: Promise<{ trigger: string }> },
) {
  const raw = await req.text(); // corpo bruto, antes de qualquer JSON.parse
  const recebida = req.headers.get("x-heropay-signature") ?? "";
  if (!assinaturaValida(raw, recebida, process.env.HEROPAY_WEBHOOK_SECRET!)) {
    return new Response(null, { status: 401 });
  }

  const { trigger } = await params;
  const evento = JSON.parse(raw);
  const pedidoId = evento.cart?.src; // o src que você mandou no link
  // insere (payment_id, trigger) em heropay_events; se já existe, responde 200 e para
  return new Response(null, { status: 200 });
}

O truque do campo src: o que você manda nele ao criar o link é salvo no carrinho e volta em cart.src em todos os webhooks daquela compra. Mandando o id do pedido, o webhook sabe exatamente qual linha atualizar, sem casar por e-mail ou valor.

E o MCP server do HeroPay?

Está em desenvolvimento e ainda não foi publicado. Quando sair, ele vai ser anunciado na página de IA e na documentação. Até lá, desconfie de qualquer pacote ou comando de instalação que se apresente como MCP oficial do HeroPay.

Na prática, o Claude Code não precisa dele para integrar. Tudo que um MCP faria no desenvolvimento, o Claude Code já faz com o terminal, sob a sua aprovação:

• Descobrir o contrato real antes de escrever código: o Claude roda o curl do passo 2, cria um link de R$ 5 no sandbox e usa a resposta verdadeira, em vez de adivinhar o formato.
• Depurar o webhook: "a venda de teste confirmou mas o pedido não virou paid; consulta GET /sales/unitary no sandbox e compara com o log da rota".
• Preparar ambiente de PR: um link por branch com src identificando o PR, para testar o fluxo inteiro no preview.

Por que colocar o HeroPay no CLAUDE.md do projeto?

Porque o Claude Code esquece o que você disse na sessão anterior, mas não esquece o CLAUDE.md. O arquivo na raiz do projeto é lido no começo de cada sessão e vira a memória do repositório: convenções, comandos, regras. Sem ele, cada pedido novo ("adiciona um plano mensal", "cria um cupom de lançamento") é uma nova chance de o Claude mandar 197 em vez de 19700, esquecer o header Accept ou liberar acesso pelo redirect.

O bloco do passo 3 foi escrito para isso. Cada linha evita um erro que custa dinheiro:

Três boas práticas para o bloco continuar útil:

• Versione o CLAUDE.md. Ele é código de time: quem entra no projeto e abre o Claude Code já recebe as regras.
• Não coloque segredo nele. O arquivo vai para o git; só nomes de variáveis, nunca valores.
• Atualize quando a integração mudar. Adicionou assinatura? Acrescente a linha "Recorrência: period no POST /payment_links; ciclo de vida pelos gatilhos subscription_*".

O mesmo bloco funciona no AGENTS.md que Codex e outras ferramentas leem, e nas regras do Cursor. Veja a integração com o Cursor.

Integrar pagamento pelo Claude Code é seguro?

É tão seguro quanto o cuidado com a chave. O Claude Code não tem credencial própria no HeroPay: ele age pelos comandos que você aprova, com a chave que você deixou no ambiente.

• A chave abre a conta inteira. A API tem endpoints de saque e de estorno, e o token os autoriza. Por isso: chave de sandbox no desenvolvimento, chave de produção só no ambiente de deploy, e nenhum curl contra a API de produção na sessão do Claude Code.
• Aprovação antes de executar. O Claude Code pede sua confirmação antes de rodar comandos no terminal. Não coloque curl contra a API do HeroPay em nenhuma lista de aprovação automática.
• Chave fora da conversa e fora do repo. Os comandos usam $HEROPAY_API_KEY, expandida pelo shell. Para impedir que o Claude abra o .env com a ferramenta de leitura, bloqueie em .claude/settings.json:

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

• Cuidado com conteúdo externo. Uma página, issue ou e-mail lido pelo Claude pode trazer instrução maliciosa escondida, o chamado prompt injection. É mais um motivo para manter a aprovação manual em qualquer comando que fale com a API.
• Revise o diff do webhook. É a única rota pública que muda status de pagamento. Os testes do passo 4 são o mínimo; leia o código.

O que o HeroPay ainda não tem, dito com clareza: o token é único por conta e não expira; não há chave restrita por escopo nem login por OAuth (a Stripe tem os dois). Se desconfiar de vazamento, regenere o token no painel e atualize o ambiente.

Dá para cobrar sem escrever código no repositório?

Dá, e o próprio Claude Code resolve. Se você só quer validar se alguém paga antes de construir o fluxo:

1. Peça no Claude Code: "Roda o curl de POST /payment_links para criar um link de R$ 97 da pré-venda do Plano Pro, com Pix e cartão em até 12x, src pre-venda". A resposta traz a URL do checkout.
2. Cole a URL no botão da landing, na bio ou no WhatsApp.
3. Pergunte depois: "Consulta GET /sales/unitary e me diz quantas vendas o link da pré-venda teve".

Como isso cobra gente de verdade, a chave precisa ser a de produção: aprove cada comando e tire a chave do ambiente do terminal quando terminar. Se preferir não usar terminal, o mesmo link sai pelo painel. O limite desse caminho: seu app não sabe quem pagou, então a liberação de acesso é manual. Quando as vendas começarem, o prompt do passo 4 transforma isso no fluxo completo. Mais sobre o link de pagamento.

Quais são as armadilhas mais comuns ao integrar pagamento pelo Claude Code?

Parsear o JSON antes de validar a assinatura

É o bug que mais aparece em código gerado. Express com express.json(), Next.js com req.json(), Rails com params: todos entregam o corpo já interpretado, e o HMAC calculado sobre um JSON re-serializado não bate com o que o HeroPay assinou. O Claude "resolve" desligando a validação, e o webhook fica aberto. Leia o corpo bruto (express.raw, req.text(), request.raw_post, request.body no Django) e só parseie depois de validar.

Chave em variável pública do front

NEXT_PUBLIC_, VITE_ e EXPO_PUBLIC_ vão para o bundle que qualquer pessoa baixa pelo navegador. Com o token, alguém cria links, lê suas vendas e consulta seu saldo. Depois da geração, peça: "Procure qualquer uso de HEROPAY_API_KEY fora de código de servidor". A resposta certa é nenhuma.

Chave colada em arquivo versionado

Quem cola o token literal no CLAUDE.md, num script de teste ou num exemplo de curl publica a chave no git. Use sempre $HEROPAY_API_KEY e deixe o valor no ambiente. Se já commitou, regenere o token no painel: apagar o commit não desfaz o vazamento.

Reais onde a API espera centavos

price_cents é inteiro: R$ 197,00 é 19700. Mandar 197 cria um pedido de R$ 1,97, que a API recusa com 422 porque o mínimo é 500. Guarde centavos no banco e só formate na tela.

Confirmar pelo redirect e não pelo webhook

Voltar para a página de obrigado não prova pagamento: o Pix pode ser pago minutos depois no celular e qualquer um digita a URL de sucesso. A fonte de verdade é o spark_payment_confirmed. Confie no evento, não no redirect.

Webhook sem idempotência

A retentativa automática pode entregar o mesmo evento mais de uma vez. Sem o índice único em (payment_id, trigger), você libera acesso em dobro ou manda dois e-mails. O reenvio da fixture no passo 6 existe para provar que isso não acontece.

Repetir POST /payment_links em timeout

A v1 não tem Idempotency-Key: cada chamada cria um link novo. Retry automático de cliente HTTP em POST gera links órfãos. Grave o id retornado e, em timeout, consulte GET /payment_links antes de criar de novo.

Webhook cadastrado no ambiente errado

Cadastrou na API de produção e está testando no sandbox (ou o contrário)? O evento nunca chega. Cada ambiente tem seus webhooks e seu segredo. Liste com GET /webhook no ambiente certo antes de depurar código.

Assinatura esperando só cartão

Links de recorrência (period: monthly, annual etc.) aceitam cartão, boleto e Pix. Na assinatura via Pix, o comprador autoriza o Pix Automático uma vez e as cobranças seguintes caem sozinhas. Se o Claude Code restringir a recorrência a cartão por ler um exemplo antigo, aponte esta regra no CLAUDE.md.

Claude Code com HeroPay, Stripe, Mercado Pago ou AbacatePay: qual escolher?

Todos estão se movendo rápido no eixo Claude Code. A tabela mostra como cada um conecta hoje.

Verificado em set/2026. Fontes: heropay.tech/precos, docs.stripe.com/mcp, stripe.com/br/pricing, anúncio do Mercado Pago para Claude Code, docs.abacatepay.com, abacatepay.com. Taxas do Mercado Pago não comparadas aqui por variarem por prazo de recebimento.

Onde os outros estão à frente, com honestidade: a Stripe tem servidor MCP remoto com OAuth e chave específica para IA, e o Mercado Pago tem plugin com comandos prontos, incluindo um que audita a integração contra o checklist oficial. O HeroPay ainda não tem MCP publicado, plugin nem OAuth. Onde o HeroPay ganha: Pix e boleto a R$ 0 para qualquer conta, checkout com parcelamento, 2 cartões e recuperação de carrinho, e uma API REST pequena o bastante para caber num prompt. Comparativos completos em Stripe vs HeroPay e AbacatePay vs HeroPay.

Quanto custa integrar pagamento pelo Claude Code?

O HeroPay não cobra pelo llms.txt, pela documentação nem por chamada de API. Você paga por transação aprovada: Pix R$ 0, boleto R$ 0 e cartão 3,49%, em até 12x. Numa venda de R$ 197 no cartão, a tarifa é R$ 6,88; no Pix, R$ 0, e os R$ 197 inteiros entram no saldo.

Verificado em set/2026. Fontes: heropay.tech/precos, stripe.com/br/pricing.

Do lado da Anthropic, o Claude Code exige plano pago do Claude ou créditos de API; o HeroPay não interfere nisso. A conta completa por método está em preços.

Comece agora

Crie a conta sandbox, cole o bloco no CLAUDE.md e mande o prompt. A primeira venda de teste sai em minutos, no seu repositório, sem fila de homologação. Quando passar no sandbox, troque a chave e vá pro ar.

Criar conta sandbox · Ler a documentação

Leia também: HeroPay para IA · API para desenvolvedores · Webhooks · Link de pagamento · Assinaturas · Preços · Integração com o Lovable · Integração com o Cursor · Glossário