HeroPay para quem constrói com IA: peça o pagamento em português e ele sai integrado

Um MCP server é um servidor que expõe ferramentas de um sistema para que uma IA como Claude, ChatGPT ou Cursor possa usá-las direto da conversa. O MCP server oficial do HeroPay está em desenvolvimento. Enquanto isso, o llms.txt entrega o mesmo resultado para quem está construindo: você cola heropay.tech/llms.txt no Claude, ChatGPT, Cursor, Lovable e outros, escreve "cria um link de R$ 197 com Pix e cartão em até 12x e a rota que recebe o webhook", e a IA lê a referência, segue para a documentação aberta em docs.heropay.tech e escreve a integração com a API REST, com valores em centavos, headers corretos e webhook validado. Pix e boleto custam R$ 0 e o cartão sai por 3,49% por transação aprovada (veja os preços).

Criar conta sandbox · Ler a documentação

O que é MCP e o que um MCP server faz?

MCP é a sigla de Model Context Protocol, um padrão aberto criado pela Anthropic e publicado em novembro de 2024 (anúncio oficial) para conectar modelos de IA a sistemas externos. Antes dele, cada ferramenta de IA precisava de uma integração própria com cada serviço. Com ele, o serviço publica um MCP server uma vez e qualquer cliente compatível (Claude Code, Cursor, Codex e outros) passa a enxergar as mesmas ferramentas.

Na prática, o protocolo tem três papéis:

• Host: o aplicativo onde você conversa com a IA (o terminal do Claude Code, o editor Cursor, o Codex).
• Cliente MCP: a peça dentro do host que conversa com um servidor específico.
• MCP server: o serviço que declara ferramentas ("criar link de cobrança", "consultar vendas"), com nome, descrição e parâmetros. A IA lê essa declaração, decide quando usar cada ferramenta e chama a API por você.

A comunicação usa JSON-RPC, o mesmo formato leve de requisição e resposta usado em muitas APIs. O ponto que importa para quem integra pagamento: a IA não precisa "adivinhar" a API a partir do treino dela. Ela recebe a lista exata do que pode fazer, com os tipos certos, e o servidor executa. Menos alucinação de endpoint, menos campo inventado. O llms.txt ataca o mesmo problema por outro lado: em vez de declarar ferramentas, entrega à IA o mapa da documentação atual.

MCP server e llms.txt: qual a diferença?

Os dois ensinam a IA a trabalhar com um sistema, mas em momentos diferentes. Um MCP server executa: a IA chama uma ferramenta e a ação acontece de verdade, na sua conta. O llms.txt ensina: é um arquivo de texto que a IA lê para saber onde está cada informação e escrever o código da sua integração. O MCP é mais cômodo quando você quer que a IA faça algo agora (gerar um link, olhar as vendas de ontem). O llms.txt resolve quando você quer que a IA escreva o código que vai fazer isso para sempre dentro do seu produto. No HeroPay, hoje, o caminho é o llms.txt com a documentação aberta; para as ações do dia a dia, a IA escreve e roda o curl que você aprovar.

Como funciona "peça e sai integrado"?

O fluxo tem três passos e funciona hoje, sem MCP:

1. Aponte: cole heropay.tech/llms.txt e docs.heropay.tech na conversa, ou deixe os dois no arquivo de instruções do projeto (CLAUDE.md, regras do Cursor, AGENTS.md).
2. Peça: descreva o que você precisa em português, do jeito que falaria com um colega de time.
3. Receba e teste: a IA escreve a rota que chama POST /payment_links, a rota do webhook com validação HMAC e o curl de teste. Você roda no sandbox, confere a resposta e só então leva o código para produção.

Na primeira vez, faça tudo no sandbox. Ele é gratuito, idêntico à produção e não passa por fila de homologação. Quando estiver satisfeito, troque a chave de sandbox pela de produção e vá pro ar.

Qual chamada a IA escreve para criar um link de pagamento?

É esta. Toda integração com o HeroPay começa por ela, e é o melhor teste para ver se a IA entendeu o contrato:

curl -X POST "https://api.beta.heropay.tech/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": "Curso de Next.js do Zero",
      "description": "Acesso ao curso",
      "price_cents": 19700,
      "absorbs_fees": false,
      "max_installments": 12,
      "payment_methods": ["pix", "credit_card", "bank_slip"],
      "src": "lancamento-setembro"
    }
  }'

A resposta 201 traz o checkout pronto em data.offer.url. Repare nos detalhes que a IA precisa acertar e que estão na documentação: o valor vai em centavos (19700, não 197), o header Accept fixa a versão 1 da API e o src volta em cart.src em todo webhook daquela compra. 401 é chave ausente ou sem Bearer; 422 costuma ser valor abaixo de 500 centavos. A chave é lida da variável $HEROPAY_API_KEY, então ela não aparece no comando nem na conversa.

Como integrar o HeroPay pelo Claude Code?

O Claude Code, a ferramenta de linha de comando da Anthropic para programar com o Claude, lê o CLAUDE.md da raiz do projeto no começo de cada sessão. Deixe ali a referência do HeroPay e as regras que a integração precisa seguir:

## 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).
- Pagamento se confirma pelo webhook spark_payment_confirmed, nunca pelo redirect do checkout.
- Testes contra a API só com a chave de sandbox. Pergunte antes de chamar qualquer endpoint que não seja de leitura.

Exemplo de pedido:

Cria um link de pagamento para o "Curso de Next.js do Zero" por R$ 197,
aceitando Pix, boleto e cartão em até 12x, com src "lancamento-setembro".
Roda o curl no sandbox e depois escreve a rota do meu app que faz a mesma chamada.

O que o Claude Code faz: propõe o curl de POST /payment_links com price_cents: 19700, pede sua aprovação para rodar, mostra a resposta com o link em data.offer.url e, em seguida, escreve a rota de servidor no padrão do seu projeto, lendo a chave do ambiente. O passo a passo completo, com o prompt pronto e o webhook, está na integração com o Claude Code.

Como integrar o HeroPay pelo Cursor?

O Cursor aceita regras de projeto em .cursor/rules. Crie uma regra com o mesmo bloco de pagamentos acima (referência no llms.txt e na documentação, headers, centavos, chave no servidor) e o agente passa a segui-lo em toda conversa daquele repositório.

Exemplo de pedido (no chat do Cursor, com o projeto aberto):

Seguindo a regra de pagamentos, escreve um script que lista as vendas
no cartão dos últimos 7 dias pela API do HeroPay, separando aprovadas
e recusadas, com o motivo das recusas. Confere os filtros na documentação.

O que o Cursor faz: consulta a referência de lista de vendas (GET /sales/unitary) na documentação, escreve o script com a chave lida do ambiente e sugere rodar contra o sandbox primeiro. Para o motivo das recusas, a documentação aponta o relatório de recusadas com motivo (GET /reports/purchase/refused/reasons_count); no webhook de recusa, o motivo da operadora vem em payment_methods.credit_card.refused_message. Veja a integração com o Cursor.

Como integrar o HeroPay pelo Codex?

O Codex, da OpenAI, lê instruções de projeto no arquivo AGENTS.md. Coloque nele o mesmo bloco de pagamentos e peça em português.

Exemplo de pedido:

Tenho R$ 5.000 para receber no cartão. Monta o curl que simula a antecipação
desse valor na API do HeroPay, roda no sandbox e me explica a resposta.

O que o Codex faz: monta a chamada de simulação e pede aprovação para rodar:

curl "https://api.beta.heropay.tech/financial/anticipation_simulation?amount_cents=500000" \
  -H "Authorization: Bearer $HEROPAY_API_KEY" \
  -H "Accept: application/vnd.herospark.com; version=1"

A resposta traz a taxa de antecipação, o valor líquido e o máximo antecipável naquele momento (o saque não tem tarifa), todos calculados pela API para a sua conta. Isso é só uma simulação: nada foi antecipado. A IA não estima taxa, ela lê o que a API devolve. Para antecipar de fato, você decide no painel em app.heropay.tech. Veja saques e antecipação.

Como usar o HeroPay no Lovable, v0, Bolt e ChatGPT?

Lovable, v0, Bolt e o chat do ChatGPT geram o código do seu app a partir da conversa. O uso é colar o link do llms.txt no início, junto com o pedido:

https://heropay.tech/llms.txt

Leia https://heropay.tech/llms.txt e a documentação em https://docs.heropay.tech
e integre o HeroPay neste app. Quero um botão "Assinar" que gera um link de
pagamento mensal de R$ 49,90, e uma rota que recebe o webhook de pagamento
confirmado, valida a assinatura HMAC e libera o acesso do usuário.

A IA lê a referência, escreve a chamada para POST /payment_links, cria a rota do webhook e pede a sua chave como variável de ambiente (nunca no código do navegador). No Lovable, a chamada fica numa edge function; veja a integração com o Lovable. Se a ferramenta não abrir links, baixe o arquivo e cole o conteúdo no chat.

O que tem dentro do llms.txt do HeroPay?

O heropay.tech/llms.txt é o mapa: um resumo do que é o HeroPay, a lista das páginas do site com descrição (preços, link de pagamento, webhooks, comparativos, guias) e o endereço da documentação da API. A AbacatePay, por exemplo, publica a referência inteira da API no próprio llms.txt (abacatepay.com/llms.txt); no HeroPay, o llms.txt aponta para a documentação aberta, e é lá que a IA encontra o contrato:

• Autenticação: token Bearer no header Authorization e o header Accept: application/vnd.herospark.com; version=1, que fixa a versão da API.
• Ambientes: produção em api.heropay.tech e sandbox em api.beta.heropay.tech. Mesmo contrato, só muda a base e a chave.
• Todos os grupos da API: link de pagamento, lista de vendas, saldo, Pix (contas e chaves), saques, simulação de antecipação, estorno, webhooks, relatórios de transações e de compras e carrinhos abandonados.
• Valores em centavos: price_cents: 19700 é R$ 197,00. O mínimo de um link é R$ 5,00 (500 centavos) e o parcelamento vai de 1 a 12 vezes.
• Paginação: nas listas de vendas, limit aceita de 10 a 1000. Fora dessa faixa, a API responde 422.
• Webhooks: a lista de gatilhos e a estrutura do payload (comprador, pagamento, oferta, carrinho, assinatura). Inclui a pegadinha de grafia: o gatilho de compra recusada é payment_credit_cart_refused, com "cart", não "card". A validação da assinatura (header X-HeroPay-Signature, HMAC SHA-256 do corpo) está explicada na página de webhooks.
• Rastreamento: o campo src do link volta em cart.src de todos os webhooks daquela compra.
• Regra de ouro: confie no evento, não no polling. Libere acesso quando o webhook de pagamento confirmado chegar, não quando o comprador voltar para a página de obrigado.

O que a IA consegue fazer hoje pela API do HeroPay?

Tudo o que a API faz, a IA consegue escrever e testar com você. Cada linha abaixo é um endpoint público, documentado em docs.heropay.tech:

A última linha pede cuidado. Saque e estorno existem na API, e a sua chave tem acesso a eles. Não deixe a IA rodar essas chamadas por conta própria: operação que tira dinheiro da sua conta passa por você, no painel ou num código que você mesmo escreveu e revisou. Veja cada função em detalhe: link de pagamento, webhooks, saques e antecipação e relatórios. Quando o MCP server oficial for publicado, as ferramentas que ele expõe e o que fica de fora serão anunciados nesta página e na documentação.

É seguro integrar pagamento com IA no HeroPay?

Tudo o que a IA faz roda sob a sua chave de API. Não existe uma credencial extra, nem um acesso "da IA" com poderes próprios. Na prática, isso significa:

• Mesmos limites e permissões: a IA enxerga e faz exatamente o que a sua chave já permite. Cada chave é específica de uma conta e não acessa dados de outra.
• A chave fica na sua máquina: ela vai na variável de ambiente, e o comando que a IA escreve só referencia a variável. Não cole a chave no chat.
• Sandbox primeiro: use a chave de sandbox enquanto testa. Um pedido mal interpretado no sandbox não gera cobrança real.
• Confirmação humana: Claude Code, Cursor e Codex pedem sua aprovação antes de rodar um comando no terminal. Mantenha essa confirmação ligada e leia cada curl antes de aceitar, principalmente os que criam coisas (link, webhook).
• Código revisado: a rota que recebe o webhook e libera acesso é a parte mais sensível. Revise a validação da assinatura antes de ir ao ar.

O que o HeroPay ainda não tem, dito com clareza: hoje a chave de API é única por conta e não expira; não existe chave restrita por escopo nem conexão por OAuth. Se você suspeitar que a chave vazou, regenere a chave no painel. Como a chave dá acesso também a saque e estorno, não a entregue a nenhuma ferramenta que rode sem a sua confirmação.

IA, SDK ou API direto: quando usar cada um?

A regra curta: a IA escreve e prototipa, o código revisado roda em produção. O seu produto não pode depender de alguém digitando num chat para cobrar. O fluxo que mais funciona na prática é pedir à IA o curl de teste, conferir a resposta real no sandbox e pedir para a mesma IA escrever o código com a API REST, que tem exemplos em 18 linguagens na documentação e OpenAPI pública. SDKs oficiais e o MCP server estão em desenvolvimento, ainda sem data.

Como o HeroPay se compara ao Stripe MCP?

O Stripe tem um MCP server maduro, e vale reconhecer: servidor remoto em mcp.stripe.com, login por OAuth, chaves específicas para agentes e confirmação humana obrigatória para operações como estorno. Hoje o Stripe está à frente em MCP. A diferença para quem vende no Brasil está no preço de cada cobrança e no acesso ao Pix.

Verificado em setembro/2026. Fontes: stripe.com/br/pricing, docs.stripe.com/mcp e heropay.tech/precos.

Em reais, numa venda de R$ 197 no cartão, o HeroPay fica com R$ 6,88 de taxa e o Stripe com R$ 8,25. No Pix, a mesma venda custa R$ 0 no HeroPay e R$ 2,34 no Stripe, se a sua conta tiver recebido o convite para Pix. Para a comparação completa de taxas, veja preços e as integrações.

Comece pelo sandbox

Crie a conta, pegue a chave de sandbox e cole heropay.tech/llms.txt na sua ferramenta de IA. Em poucos minutos você pede o primeiro link em português, roda o curl e vê a cobrança aparecer na sua conta de teste. Quando estiver certo, troque a chave e vá pro ar.

Criar conta sandbox · Ler a documentação

Continue por aqui: preços · link de pagamento · webhooks · integrações · glossário · comunidade