Aceite pagamentos no seu app do Lovable: Pix a R$ 0 e no ar em minutos

Para adicionar pagamento no Lovable com Pix, você cria uma conta sandbox no HeroPay, cola heropay.tech/llms.txt no chat do Lovable e manda um prompt pedindo o fluxo de cobrança. O Lovable escreve a edge function que chama POST /payment_links, a tela de pedido e o webhook que libera o acesso. Você testa no sandbox, troca a chave e vá pro ar. Do app Lovable à primeira venda em minutos, com Pix a R$ 0 por transação, boleto a R$ 0 e cartão em até 12x.

Criar conta sandbox · Ler a documentação

Como adicionar pagamento no Lovable com o HeroPay?

São cinco passos. Os três primeiros acontecem em menos de dez minutos; o quarto depende de quanto você quer testar.

Leia https://heropay.tech/llms.txt e a documentação em https://docs.heropay.tech e use as duas como referência da API HeroPay neste projeto. Não invente endpoints nem campos que não estejam na documentação.

Quero aceitar pagamentos neste app usando a API HeroPay (referência: https://heropay.tech/llms.txt e https://docs.heropay.tech). Siga exatamente estas regras.

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

1. BANCO DE DADOS
Crie a tabela "orders" com: id (uuid, padrão gen_random_uuid()), user_id (referência ao usuário logado), product_key (texto), amount_cents (inteiro), status (texto: pending, paid, refunded, canceled; padrão pending), checkout_url (texto), heropay_payment_link_id (inteiro), paid_at (timestamp, nulo), created_at (timestamp, padrão now()).
Ative RLS: o usuário só lê os próprios pedidos e NUNCA escreve em status, amount_cents ou paid_at. Só as edge functions, com service role, alteram esses campos.
Crie também a tabela "products" com product_key, name, description e price_cents, e cadastre o produto acima. O preço vive no servidor, nunca no front.

2. EDGE FUNCTION "create-checkout"
- Exige usuário autenticado.
- Recebe apenas product_key. Nunca aceite preço vindo do cliente.
- Busca o preço em "products" e cria um pedido "pending" em "orders".
- 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": <preço em centavos, inteiro, mínimo 500>,
      "absorbs_fees": true,
      "max_installments": [12],
      "payment_methods": ["pix", "credit_card", "bank_slip"],
      "src": "<id do pedido>"
    }
  }
- Da resposta, salve data.id em heropay_payment_link_id e data.offer.url em checkout_url.
- Devolve ao front só o checkout_url e o id do pedido.
- Leia HEROPAY_API_KEY e HEROPAY_API_URL com Deno.env.get. A chave nunca vai para o código do front, para o repositório nem para logs.
- Se a API responder erro, devolva uma mensagem amigável e registre o corpo do erro no log da função.

3. FRONT
- Botão "Comprar" na página do produto: chama create-checkout, abre o checkout_url em nova aba e leva o usuário para /pedido/:id.
- Página /pedido/:id: mostra "Aguardando pagamento" enquanto status = pending e atualiza sozinha (Realtime do banco ou consulta a cada 5 segundos). Quando status = paid, mostra "Pagamento confirmado" e libera o acesso.
- Nunca libere acesso só porque o usuário voltou do checkout. Quem libera é o status "paid" gravado pelo webhook.

4. EDGE FUNCTION "heropay-webhook"
- Pública (sem exigir JWT do Supabase), só aceita POST.
- Valide a autenticidade do evento antes de parsear o JSON: o header X-HeroPay-Signature traz um HMAC SHA-256 do corpo bruto, calculado com HEROPAY_WEBHOOK_SECRET (lido com Deno.env.get). Compare em tempo constante, aceitando o HMAC em hexadecimal ou em base64. Assinatura ausente ou diferente: responda 401 e descarte.
- Leia o gatilho do evento e o campo cart.src, que é o id do pedido.
- spark_payment_confirmed: marque o pedido como paid e grave paid_at, mas só se o valor pago bater com amount_cents. Seja idempotente: se já está paid, responda 200 e não faça nada.
- refunded ou chargeback_request: marque como refunded e revogue o acesso.
- Responda 200 rápido. Evento com cart.src desconhecido: registre no log e responda 200.

5. ENTREGA
Ao terminar, me mostre a URL pública da função heropay-webhook e um comando curl para eu registrar o webhook na HeroPay. Não crie nada fora do que foi pedido.

for trigger in spark_payment_confirmed refunded chargeback_request; do
  curl -s -X POST https://api.beta.heropay.tech/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\":\"https://SEU-PROJETO.supabase.co/functions/v1/heropay-webhook\",\"request_method\":\"post\"}}"
done

O que o Lovable vai gerar?

Com o prompt acima, o Lovable monta quatro peças. Vale saber o que cada uma faz para revisar o código antes de publicar.

A chamada central fica parecida com isto:

const res = await fetch(`${Deno.env.get("HEROPAY_API_URL")}/payment_links`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${Deno.env.get("HEROPAY_API_KEY")}`,
    Accept: "application/vnd.herospark.com; version=1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    payment_link: {
      name: product.name,
      price_cents: product.price_cents, // 19700 = R$ 197,00
      absorbs_fees: true,
      max_installments: 12,
      payment_methods: ["pix", "credit_card", "bank_slip"],
      src: order.id, // volta no webhook em cart.src
    },
  }),
});
const { data } = await res.json();
// data.offer.url é o checkout pronto

O truque está no campo src. O que você manda nele é 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 de orders atualizar, sem casar por e-mail ou valor.

Quer menos chamadas? Crie um link por produto uma vez só e acrescente ?src=<id-do-pedido> na URL a cada compra. O efeito no webhook é o mesmo.

Dá para cobrar no Lovable sem escrever código?

Dá. Se você só quer validar se alguém paga, pule a edge function:

1. No painel, crie um link de pagamento com nome, preço e métodos.
2. No Lovable, peça: "Adicione um botão Comprar agora na página de preços que abre [URL do link] em nova aba."
3. Acompanhe as vendas no painel.

O limite desse caminho: o app não sabe quem pagou. Você libera acesso manualmente ou, quando as vendas começarem, evolui para o fluxo com webhook acima. Para capturar a origem, acrescente ?src=instagram (ou o nome da campanha) na URL do botão e veja isso chegar nos relatórios.

Quais são as armadilhas mais comuns ao integrar pagamento no Lovable?

Chave exposta no front

É o erro mais caro. Se o token aparece em um arquivo .tsx, em import.meta.env do Vite ou em uma variável com prefixo VITE_, ele vai parar no bundle que qualquer pessoa baixa pelo navegador. Com o token, alguém cria links, lê suas vendas e consulta seu saldo.

Como evitar: o token vive só em Secrets e só é lido dentro de edge function com Deno.env.get. Depois que o Lovable gerar o código, peça: "Procure no projeto qualquer uso de HEROPAY_API_KEY fora de supabase/functions e me mostre." A resposta certa é nenhuma. Se a chave vazou, gere outra no painel na hora.

Valor em reais onde a API espera centavos

price_cents é inteiro em centavos: R$ 197,00 é 19700. Mandar 197 cria um link de R$ 1,97, que a API recusa porque o mínimo é R$ 5,00 (500). Mandar 197.00 como float também dá problema. Guarde centavos no banco e só formate em reais na tela.

Preço vindo do navegador

Se a edge function aceita price_cents do front, qualquer um edita a requisição e compra seu plano por R$ 5. O front manda só o identificador do produto; o preço sai da tabela products.

Confirmar pelo redirect e não pelo webhook

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

Webhook sem validação ou sem idempotência

Uma URL pública que marca pedidos como pagos precisa validar a assinatura HMAC do evento, senão qualquer um forja um "pago". E o mesmo evento pode chegar mais de uma vez por causa do retry: marcar paid só se ainda estiver pending evita liberar em dobro ou mandar dois e-mails.

Assinatura esperando Pix

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, sem cartão e sem churn involuntário. Detalhes em assinaturas.

Por que Pix a R$ 0 muda a conta de um micro-SaaS?

Em ticket baixo, taxa fixa por transação come a margem antes do percentual. Veja 1.000 vendas de R$ 29,90 em Pix (um pacote de créditos, por exemplo):

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

R$ 800 por mil vendas é um mês de servidor, de ferramenta de e-mail ou de anúncio. Em micro-SaaS, onde cada real de margem define se o projeto se paga, cobrar Pix de graça muda a decisão de preço: você pode dar desconto no Pix sem perder dinheiro para o gateway.

No cartão, o HeroPay também fica mais barato que a Stripe BR em qualquer valor de venda: numa venda de R$ 29,90, o HeroPay cobra 3,49% (R$ 1,04) e a Stripe BR cobra 3,99% + R$ 0,39 (R$ 1,58). O que a Stripe tem a mais aqui é a conexão nativa com o Lovable e o suporte oficial (veja a tabela abaixo). Para ticket baixo, o Pix a R$ 0 continua sendo o melhor caminho; para ticket alto, o cartão em até 12x com aprovação de 93%+ trabalha a seu favor. A conta completa está em preços.

Lovable Payments, Stripe ou HeroPay: qual usar?

Verificado em set/2026. Fontes: docs.lovable.dev/features/payments, docs.lovable.dev/integrations/stripe, stripe.com/br/pricing.

Resumo honesto: se você vende em dólar para o mundo e quer zero configuração, o pagamento nativo do Lovable é o caminho mais curto. Se o seu cliente é brasileiro e paga em Pix, a conta muda: o HeroPay cobra R$ 0 no Pix e entrega um checkout com parcelamento, Apple Pay, Google Pay e recuperação de carrinho. A própria documentação do Lovable diz que outros provedores entram por edge function com sua conta e sua chave; é exatamente o fluxo desta página.

Comece agora

Crie a conta sandbox, cole o llms.txt no Lovable e faça a primeira venda de teste hoje. 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: Link de pagamento · Pix · Webhooks · Checkout · Preços · Integrações · Glossário