API de pagamento que integra em minutos, não em semanas

A HeroPay é uma API de pagamento REST para o Brasil: você cria um link de pagamento com Pix, cartão em até 12x e boleto com uma chamada POST /payment_links, recebe a confirmação por webhook assinado e consulta saldo, saques, estornos e relatórios pelos mesmos endpoints. Autenticação por Bearer JWT, sandbox gratuito idêntico à produção, referência OpenAPI pública e exemplos em 18 linguagens. Pix e boleto custam R$ 0 por transação.

Criar conta sandbox · Ler a documentação

Como integrar uma API de pagamento em 5 minutos?

Três passos: pegue a chave, crie o link, escute o webhook. Nada de contrato, nada de homologação.

export HEROPAY_API_URL="https://api.beta.heropay.tech"   # sandbox
export HEROPAY_JWT_TOKEN="seu-jwt-do-sandbox"

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": "Plano Pro",
      "description": "Acesso ao Plano Pro",
      "price_cents": 9700,
      "absorbs_fees": true,
      "max_installments": 12,
      "payment_methods": ["pix", "credit_card", "bank_slip"],
      "src": "lancamento-setembro"
    }
  }'

{
  "message": "Payment link created successfully",
  "data": {
    "id": 136,
    "name": "Plano Pro",
    "description": "Acesso ao Plano Pro",
    "price_cents": 9700,
    "absorbs_fees": true,
    "max_installments": 12,
    "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=lancamento-setembro",
      "accepted_payment_methods": ["pix", "credit_card", "bank_slip"]
    },
    "created_at": "2026-09-23T10:07:01.929-03:00",
    "updated_at": "2026-09-23T10:07:01.929-03:00"
  }
}

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"
    }
  }'

Mapa de funções da API

A API v1 da HeroPay tem mais de 70 endpoints organizados nos grupos abaixo. Cada grupo tem página própria na referência da API.

Link de pagamento

O que faz: cria, lista, consulta e exclui links de checkout com Pix, cartão e boleto, em pagamento único ou recorrente. Aceita parcelamento de 1 a 12x (parcela mínima de R$ 1,99), valor mínimo de R$ 5,00, vendas internacionais multi-moeda (enable_international_sales, só em link avulso) e rastreamento de origem (src) que volta em cart.src em todo webhook. Endpoint principal: POST /payment_links · também GET /payment_links (paginado com page e items), GET /payment_links/{id}, DELETE /payment_links/{id}. Caso de uso: o SaaS gera um link por plano, o infoprodutor gera um link por campanha com src=instagram e sabe de onde veio cada venda. Docs: Links de pagamento · Criar link · Pagamento internacional · Página do produto: /link-de-pagamento

Assinaturas e pagamentos recorrentes

O que faz: transforma o link em assinatura ao enviar period (monthly, quarterly, semiannual, annual), com renovação ilimitada (frequency_type: unlimited) ou por número de ciclos (limited + frequency_limit). A cobrança de cada ciclo e o reprocessamento de falhas são automáticos; o cancelamento é por API. Endpoint principal: POST /payment_links com period · POST /recurring_payment/cancel (com recurring_payment_id) · GET /sales/recurring. Caso de uso: micro-SaaS com plano mensal e anual; mentoria de 12 meses que encerra sozinha no último ciclo. Docs: Modelos de pagamento · Pagamentos recorrentes · Página do produto: /assinaturas

Checkout

O que faz: todo link de pagamento abre o checkout HeroPay hospedado, com Pix, cartão em até 12x, boleto, Apple Pay e Google Pay, compra 1-click, 2 cartões e Parcelamento Inteligente. Você não mantém formulário de cartão nem escopo de PCI no seu front. Endpoint principal: a URL em data.offer.url do POST /payment_links. Caso de uso: colocar cobrança num app feito no Lovable sem construir tela de pagamento. Docs: Links de pagamento · Página do produto: /checkout

Pix (conta e chave)

O que faz: cadastra e lista as chaves Pix de recebimento (e-mail, telefone, CPF/CNPJ ou aleatória) e define a chave padrão para saques. Toda chave precisa pertencer ao mesmo CPF/CNPJ do titular da conta. A cobrança Pix para o comprador nasce do link de pagamento (payment_methods: ["pix"]), com QR Code e copia e cola no checkout, à vista ou com parcelamento via Pix. Endpoint principal: POST /financial/pix_accounts · GET /financial/pix_accounts · POST /financial/pix_accounts/{id}/set_as_default. Caso de uso: onboarding de um vendedor que cadastra a chave Pix no seu painel e já sai sacando. Docs: Chave Pix · API Pix · Página do produto: /pix

Lista de vendas e transações

O que faz: busca vendas avulsas e recorrentes com filtros e lista transações por status (paga, pendente, recusada, cancelada). Separa compra (a intenção do cliente) de transação (cada tentativa de cobrança), o que evita contar venda em dobro. Endpoint principal: GET /sales/unitary · GET /sales/recurring · GET /transactions/by_status. Caso de uso: conciliar as vendas do dia com seu banco de dados; mostrar histórico de cobranças de um assinante. Docs: Transações vs compras · Lista de vendas

Saldo

O que faz: devolve saldo disponível e a receber (em centavos e formatado), valor disponível para saque, valor antecipável e se a conta permite antecipação. Endpoint principal: GET /financial/balance. Caso de uso: exibir "você tem R$ X para sacar" dentro do seu produto. Docs: Saldo

Saques

O que faz: solicita saque do saldo disponível para uma chave Pix cadastrada e lista o histórico de saques. Endpoint principal: POST /financial/withdrawals (com amount_cents e pix_account_id) · GET /financial/withdrawals. Caso de uso: marketplace ou plataforma que automatiza o repasse semanal do vendedor. Docs: Saques e antecipação · API de saques · Página do produto: /saques-e-antecipacao

Simulação de antecipação

O que faz: simula quanto das vendas no cartão pode ser antecipado e com qual tarifa, antes de você pedir o dinheiro. A resposta traz o valor máximo antecipável e as taxas aplicadas naquela operação. Endpoint principal: GET /financial/anticipation_simulation (com amount_cents). Caso de uso: mostrar ao vendedor o custo exato de antecipar antes de ele confirmar. Docs: Simulação de antecipação

Estorno

O que faz: solicita o estorno de um pagamento pelo ID e devolve valores, taxas, data limite e status do estorno. Endpoint principal: POST /refund (com refund.payment_id). Caso de uso: botão "reembolsar" no seu painel de suporte, sem abrir outro sistema. Docs: Estorno de pagamento

Webhooks

O que faz: cadastra, lista, ativa, desativa e remove webhooks por gatilho. Cada evento chega como POST JSON assinado com HMAC e com retentativa automática se seu endpoint falhar. São 9 gatilhos: spark_payment_confirmed, spark_payment_boleto_created, payment_pix_created, payment_credit_cart_refused, refunded, chargeback_request, subscription_activate, subscription_update e subscription_cancel. Endpoint principal: POST /webhook · GET /webhook · PUT /webhook/{id}/enable · PUT /webhook/{id}/disable · DELETE /webhook/{id}. Caso de uso: liberar acesso quando o pagamento confirma, suspender quando a assinatura cancela, alertar o time em chargeback. Docs: Webhooks · API de webhooks · Página do produto: /webhooks

Relatórios de transações

O que faz: 30 endpoints prontos de analytics financeiro, sem você montar ETL.

• Pagas (/reports/transaction/paid/*): receita bruta, receita líquida, líquida mensal, líquido após taxas, contagem de transações, transações por método, distribuição por método de pagamento, último pagamento, receita por oferta, mais vendidos, recibo fiscal e relatório completo.
• Pendentes (/reports/transaction/pending/*): valor total pendente, pendentes por oferta, transações expirando e relatório completo.
• Reembolsadas (/reports/transaction/refunded/*): valor de estornos e chargebacks, estornos mensais, taxas de chargeback, taxas não reembolsáveis, último estorno, contagem por status, ofertas e produtos mais reembolsados e relatório completo.
• Resumos (/reports/transaction/summary/*): pagas, abertas, reembolsadas, reembolsadas e chargebacks.
• Jornada e funil de conversão: GET /reports/transaction/journey.

Endpoint principal: GET /reports/transaction/paid/net_value. Caso de uso: dashboard de receita líquida no seu admin; boletos prestes a vencer para disparar lembrete. Docs: Relatórios de transações

Relatórios de compras

O que faz: 23 endpoints de análise de negócio.

• Recorrência e assinaturas (/reports/purchase/subscriptions/*): receita bruta, líquida e após taxas, receita por oferta, contagem por status, vendas mensais, última venda, mais vendidos e relatório completo.
• Estratégia de vendas (/reports/purchase/sales_strategy/*): receita bruta, líquida e após taxas, últimas vendas, contagem mensal, contagem por modalidade, receita por oferta, mais vendidos e relatório completo.
• Recusadas com motivo (/reports/purchase/refused/*): vendas recusadas e contagem de motivos de recusa.
• Resumos (/reports/purchase/summary): geral, de assinaturas e de estratégia de vendas.

Endpoint principal: GET /reports/purchase/refused/reasons_count. Caso de uso: descobrir que a maior causa de recusa é limite e ligar o parcelamento; medir churn de assinatura por mês. Docs: Relatórios de compras

Carrinhos abandonados

O que faz: lista, por período, os checkouts em que o comprador preencheu os dados de contato e não pagou. Cada acesso ao link cria um carrinho; uma mesma sessão pode ter várias tentativas. Endpoint principal: GET /reports/tracking/abandoned_carts (com start_date e end_date). Caso de uso: puxar os abandonos da última hora e disparar recuperação pelo seu CRM. Docs: Carrinhos · Obter carrinhos abandonados

O que a API v1 ainda não tem

Honestidade de dev para dev: split de pagamento não tem endpoint público na v1 (veja o status em /split); não há endpoint para criar uma cobrança Pix avulsa fora do link de pagamento (o Pix sempre sai pelo checkout); e não há header Idempotency-Key. Quando isso mudar, vai estar no changelog da documentação.

Sandbox e produção: o que muda?

Só a chave. O sandbox roda o mesmo contrato, os mesmos endpoints e os mesmos webhooks da produção, é gratuito e não passa por homologação.

Deixe a URL base e o token em variáveis de ambiente. Deploy em produção vira troca de duas variáveis, não um projeto.

Como funciona a autenticação da API?

Bearer JWT em todas as requisições. O token é gerado no painel app.heropay.tech, é escopado à sua conta (não enxerga dados de outra), não expira e pode ser regenerado a qualquer momento se vazar.

POST /payment_links HTTP/1.1
Host: api.heropay.tech
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/vnd.herospark.com; version=1
Content-Type: application/json

Token ausente ou inválido responde 401 Unauthorized. Regra de ouro: o token vive no servidor. Nunca em código de cliente, app mobile ou repositório público.

Como funciona o versionamento?

Pelo header Accept: application/vnd.herospark.com; version=1. A versão atual é a 1, estável e recomendada. Se você não mandar o header, a API usa a versão mais recente disponível, o que é ótimo para testar e perigoso em produção: fixe version=1 e sua integração não muda sozinha. Quando sair uma versão nova, ela vem com documentação das mudanças, guia de migração e período de transição. Detalhes em Versionamento.

Como funcionam os webhooks assinados?

Você cadastra uma URL pública por gatilho com POST /webhook. A cada evento, a HeroPay envia um POST JSON com assinatura HMAC do corpo; você recalcula com o segredo do webhook e descarta o que não bater. Se seu endpoint não responder 2xx, o envio é retentado automaticamente.

A assinatura vem no header X-HeroPay-Signature: um HMAC SHA-256 do corpo bruto da requisição, calculado com o segredo do seu webhook. O exemplo compara a assinatura recebida com o HMAC em hexadecimal e em base64, para o seu código não depender da codificação; detalhes em webhooks.

import crypto from "node:crypto";

// Express com body cru (express.raw({ type: "application/json" }))
app.post("/webhooks/heropay", (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 valida = [mac.toString("hex"), mac.toString("base64")].some(
    (esperada) =>
      recebida.length === esperada.length &&
      crypto.timingSafeEqual(Buffer.from(recebida), Buffer.from(esperada))
  );
  if (!valida) {
    return res.sendStatus(401);
  }

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

O payload segue um template padrão com buyer, payment, offer, product, cart (com cart.src, a origem que você mandou no link), subscription, installments e payment_methods (dados de Pix, boleto e cartão; em recusa, o motivo da operadora vem em payment_methods.credit_card.refused_message). Atenção à grafia do gatilho de recusa: payment_credit_cart_refused, com cart.

Quais SDKs e linguagens a HeroPay suporta?

A referência da API tem exemplos prontos para copiar em 18 linguagens: cURL, Python, Node.js, JavaScript, Ruby, PHP, Go, Java, C#, C, Objective-C, Swift, Kotlin, Dart, Rust, OCaml, R e PowerShell. A especificação OpenAPI é pública: gere seu próprio cliente com qualquer gerador OpenAPI.

SDKs oficiais estão em desenvolvimento, ainda sem data de publicação. Até lá, qualquer cliente HTTP resolve: é REST com JSON e dois headers, e os exemplos da documentação cobrem as 18 linguagens acima.

Como integrar a HeroPay com IA?

A HeroPay foi desenhada para ser integrada por IA. Duas portas de entrada:

llms.txt + documentação aberta. O heropay.tech/llms.txt resume a HeroPay para IAs e aponta para a referência da API em docs.heropay.tech. Cole no Claude, ChatGPT, Cursor, Lovable e outros e peça em português: "integra a HeroPay no meu app usando https://heropay.tech/llms.txt e https://docs.heropay.tech: um botão que cria um link de R$ 97 com Pix e cartão em 12x e uma rota que valida o webhook". A ferramenta escreve o código que chama a API REST, com os endpoints e headers da documentação.

API REST direta. O mesmo curl do início desta página é o que a IA vai escrever. Peça para ela rodar a chamada no sandbox antes de colocar no seu código e confira a resposta.

MCP server. O MCP server oficial da HeroPay está em desenvolvimento. Enquanto isso, o llms.txt entrega o mesmo resultado no desenvolvimento: a IA lê a referência e escreve a integração. Veja a página de IA.

Guias passo a passo por ferramenta em /integracoes.

Comece agora

Primeiro link de pagamento em 5 minutos, sem cartão de crédito e sem falar com vendas.

Criar conta sandbox · Ler a documentação

Continue por aqui: Preços · Link de pagamento · Pix · Assinaturas · Webhooks · Relatórios · Integrações com IA · Glossário