Gerador de link de pagamento: monte o curl da API

Q: Como gerar um link de pagamento pela API?

Faça um POST /payment_links com os headers Authorization: Bearer e Accept: application/vnd.herospark.com; version=1, mandando o objeto payment_link com price_cents (valor em centavos) e absorbs_fees, que são obrigatórios. Opcionalmente, inclua nome, descrição, parcelas, métodos, recorrência e src. A resposta 201 traz a URL do checkout em data.offer.url. Este gerador monta o comando a partir de um formulário e valida as regras da API antes de você rodar.

Q: Qual o valor mínimo de um link de pagamento?

R$ 5,00, ou price_cents 500. No cartão parcelado, cada parcela também precisa ter pelo menos R$ 1,99, então um link de R$ 20 aceita no máximo 10x. Se você pedir mais parcelas do que o valor permite, a API responde 422; o gerador calcula o máximo e oferece o ajuste com um clique. O máximo absoluto é 12 parcelas.

Q: Como criar um link de assinatura?

Mande o campo period com monthly, quarterly, semiannual ou annual. A partir daí o link cobra automaticamente a cada ciclo. Com frequency_type unlimited, renova até o cancelamento; com limited e frequency_limit, encerra sozinho depois de N cobranças, útil para mentoria de 12 meses. No gerador, escolha Assinatura e os campos aparecem. Vendas internacionais valem só para pagamento único.

Q: Como saber de onde veio cada venda do link?

Com o campo src. Mande src whatsapp na criação e a URL volta com ?src=whatsapp; o valor é salvo no carrinho e entregue em cart.src em todos os webhooks daquela compra, do pagamento confirmado ao chargeback. Aceita letras, números e os caracteres ponto, sublinhado, hífen e til, até 255 caracteres. O gerador corrige espaços e acentos sozinho e sugere o valor válido.

Este gerador de link de pagamento monta, a partir de um formulário simples, a chamada real da API do HeroPay que cria o link: o corpo JSON do POST /payment_links e o curl pronto para colar no terminal, além das versões em Node e Python e de um prompt para o Claude ou o Cursor. Você escolhe valor, métodos (Pix, cartão e boleto), parcelas, recorrência e a origem da venda; a ferramenta valida tudo com as mesmas regras da API e mostra quanto sobra de cada venda. A página não chama a API nem pede a sua chave: você roda o comando no sandbox, de graça, e recebe a URL do checkout em data.offer.url.

Criar conta sandbox Ler a documentação

Resumo

O essencial em 60 segundos

Um link de pagamento no HeroPay é uma chamada: POST /payment_links com payment_link.price_cents e payment_link.absorbs_fees, que são os dois campos obrigatórios; a resposta 201 traz a URL do checkout em data.offer.url.
O valor vai sempre em centavos: R$ 149,00 é 14900. O mínimo é R$ 5,00 (500) e cada parcela precisa ter pelo menos R$ 1,99.
Sem payment_methods, a API aceita Pix e cartão; para incluir boleto, mande ["pix", "credit_card", "bank_slip"].
Mandar period transforma o link em assinatura (mensal, trimestral, semestral ou anual), com renovação até o cancelamento ou por N ciclos.
O campo src marca a origem da venda (whatsapp, bio-instagram) e volta em cart.src em todos os webhooks daquela compra.
O gerador roda só no seu navegador: não chama a API, não pede token e usa a variável $HEROPAY_JWT_TOKEN no comando, para a chave nunca ir parar em código cliente.
Criar link é grátis: no HeroPay, Pix e boleto custam R$ 0 e o cartão custa 3,49% por venda aprovada, em até 12x (setembro de 2026, /precos).

A ferramenta

curl -X POST "https://api.beta.heropay.tech/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",
      "price_cents": 14900,
      "absorbs_fees": false,
      "max_installments": 12,
      "payment_methods": ["pix", "credit_card"],
      "src": "site"
    }
  }'

{
  "payment_link": {
    "name": "Plano Pro",
    "price_cents": 14900,
    "absorbs_fees": false,
    "max_installments": 12,
    "payment_methods": ["pix", "credit_card"],
    "src": "site"
  }
}

const res = await fetch("https://api.beta.heropay.tech/payment_links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HEROPAY_JWT_TOKEN}`,
    Accept: "application/vnd.herospark.com; version=1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "payment_link": {
      "name": "Plano Pro",
      "price_cents": 14900,
      "absorbs_fees": false,
      "max_installments": 12,
      "payment_methods": ["pix", "credit_card"],
      "src": "site"
    }
  }),
});
const { data } = await res.json();
console.log(data.offer.url);

import os, requests
r = requests.post(
    "https://api.beta.heropay.tech/payment_links",
    headers={
        "Authorization": f"Bearer {os.environ['HEROPAY_JWT_TOKEN']}",
        "Accept": "application/vnd.herospark.com; version=1",
    },
    json={
        "payment_link": {
            "name": "Plano Pro",
            "price_cents": 14900,
            "absorbs_fees": False,
            "max_installments": 12,
            "payment_methods": ["pix", "credit_card"],
            "src": "site",
        },
    },
)
print(r.json()["data"]["offer"]["url"])

Cria um link de pagamento de R$ 149,00 chamado "Plano Pro", aceitando Pix e cartão em até 12x com os juros pagos pelo comprador, com origem "site". Me devolve a URL.

Cole junto com https://heropay.ai/llms.txt no Claude, ChatGPT, Cursor, Lovable e outros.

Resposta esperada (201 Created)

{
  "message": "Payment link created successfully",
  "data": {
    "id": "<gerado pela API>",
    "name": "Plano Pro",
    "price_cents": 14900,
    "absorbs_fees": false,
    "max_installments": 12,
    "period": "unitary",
    "public_id": "<gerado pela API>",
    "offer": {
      "kind": "payment_link",
      "url": "https://pay.beta.herospark.com/<public_id>-<offer_id>?src=site",
      "accepted_payment_methods": ["pix", "credit_card"]
    }
  }
}

O link que você manda para o cliente é data.offer.url, já com o src.

Quanto sobra por venda

Método	Tarifa HeroPay	Você recebe
Pix	R$ 0	R$ 149,00
Cartão	R$ 5,20 (3,49%)	R$ 143,80

Taxa de parcelamento de 2,29% repassada ao comprador; você recebe 20% dela. Tarifas de /precos, setembro de 2026.

Valor do link: R$ 149,00.

Próximo passo

Cadastre o webhook spark_payment_confirmed para liberar o acesso quando o pagamento cair. Detalhes e validação da assinatura em /webhooks.

curl -X POST "https://api.beta.heropay.tech/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://seu-servidor.com/webhooks/heropay",
      "request_method": "post"
    }
  }'

Criar conta sandbox e rodar este comando Ler a referência do endpoint

Roda só no seu navegador: não chama a API e não pede a sua chave. Tipo atual: pagamento único.

De onde vem cada regra

Toda regra do gerador vem da referência pública da API, gerada da OpenAPI do HeroPay, e da documentação em prosa, consultadas em setembro de 2026:

Regra	Fonte
Endpoint, headers e os campos obrigatórios `price_cents` e `absorbs_fees`	Criar link de pagamento
Mínimo de 500 centavos, 1 a 12 parcelas, parcela mínima de R$ 1,99	idem
Métodos `pix`, `bank_slip`, `credit_card` e o padrão Pix + cartão	idem
`period`, `frequency_type` e `frequency_limit` da recorrência	idem e Links de pagamento
`src` com letras, números e `. _ - ~`, até 255 caracteres, devolvido em `cart.src`	Links de pagamento e Webhooks
Bearer JWT e `Accept: application/vnd.herospark.com; version=1`	Autenticação
Tarifas usadas no "quanto sobra"	docs.heropay.tech/fees e /precos

O que cada campo do POST /payment_links faz?

Campo	Obrigatório	O que faz	Exemplo
`price_cents`	Sim	Valor do produto, em centavos. Mínimo 500 (R$ 5,00).	`14900` = R$ 149,00
`absorbs_fees`	Sim	`true`: você paga os juros quando o comprador parcela. `false`: os juros entram no valor final do comprador.	`false`
`name`	Não	Nome do link na listagem e nos relatórios.	`"Plano Pro"`
`description`	Não	Texto que aparece na página de pagamento.	`"Acesso por 12 meses"`
`max_installments`	Não	Parcelas máximas no cartão, de 1 a 12; padrão 1. Cada parcela precisa ter pelo menos R$ 1,99.	`12`
`payment_methods`	Não	Métodos aceitos. Padrão: Pix e cartão.	`["pix", "credit_card", "bank_slip"]`
`period`	Não	Transforma o link em assinatura.	`"monthly"`
`frequency_type`	Não	Em assinatura: `unlimited` (até cancelar) ou `limited` (N ciclos).	`"limited"`
`frequency_limit`	Se `limited`	Quantos ciclos a assinatura cobra antes de encerrar sozinha.	`12`
`enable_international_sales`	Não	Abre o checkout multimoeda. Só em pagamento único.	`true`
`src`	Não	Origem da venda; entra na URL e volta em `cart.src` nos webhooks.	`"bio-instagram"`

Dois campos merecem atenção especial:

absorbs_fees é sobre juros do parcelamento, não sobre a tarifa do HeroPay. A tarifa de 3,49% do cartão é sempre do vendedor. O campo decide só quem paga os juros quando o comprador parcela: vender "12x sem juros" é true.
src substitui a concatenação manual. Mande "src": "whatsapp" e a URL já volta com ?src=whatsapp. O mesmo produto pode ter um link por canal e o webhook conta de onde veio cada venda. Mais em link de pagamento.

Quais erros o gerador evita?

As cinco armadilhas mais comuns de quem integra link de pagamento, e o que a ferramenta faz com cada uma:

Mandar reais em vez de centavos. "price_cents": 149 cria um link de R$ 1,49, que a API recusa por estar abaixo do mínimo. O gerador converte o valor digitado e mostra os dois lado a lado.
Parcela abaixo de R$ 1,99. Um produto de R$ 20 em 12x dá parcelas de R$ 1,67 e gera 422. O gerador sugere o máximo possível (10x).
Chave de API no front-end. O token do HeroPay não expira e dá acesso à conta inteira; ele nunca deve ir para o navegador ou para o app. O gerador usa sempre variável de ambiente e o comando é para rodar no seu servidor ou terminal.
Repetir a chamada depois de um timeout. POST /payment_links não é idempotente: duas chamadas iguais criam dois links. Grave o id da resposta e, em caso de dúvida, confira GET /payment_links antes de repetir.
Liberar acesso pela página de obrigado. Confie no evento, não no retorno do cliente: libere o produto quando chegar o webhook spark_payment_confirmed, assinado no header X-HeroPay-Signature com HMAC SHA-256. Veja /webhooks.

Outras regras que valem saber antes de ir pro ar: a v1 não tem edição de link (sem PUT; para mudar o preço, crie outro e exclua o antigo com DELETE /payment_links/{id}), não existe link de valor livre e o link aceita vendas ilimitadas até ser excluído.

Do sandbox à produção em três passos

Crie a conta sandbox em app.heropay.tech, sem cartão e sem homologação, e copie o token JWT nas configurações de API. Guarde em HEROPAY_JWT_TOKEN.
Rode o curl do gerador com o ambiente Sandbox. A resposta 201 traz data.offer.url: abra e confira o checkout de teste.
Troque a chave e a URL base para https://api.heropay.tech e vá pro ar. O código é o mesmo.

Prefere não escrever código? Crie o link no painel ou peça ao Claude, ChatGPT, Cursor, Lovable e outros, com o llms.txt.

Guias e ferramentas relacionados

Link de pagamento no HeroPay: a página completa da feature, com casos de uso e limites.
Assinaturas e Pix Automático: quando o link vira recorrência.
Webhooks: como validar a assinatura HMAC e a lista de gatilhos.
API para desenvolvedores e HeroPay com IA.
Calculadora de taxas: quanto o link custa no seu mix.
Glossário: sandbox, HMAC, idempotência.

Criar conta sandbox Ler a documentação

Perguntas frequentes sobre o gerador de link de pagamento

Como gerar um link de pagamento pela API?

Faça um POST /payment_links com os headers Authorization: Bearer <token> e Accept: application/vnd.herospark.com; version=1, mandando o objeto payment_link com price_cents (valor em centavos) e absorbs_fees, que são obrigatórios. Opcionalmente, inclua nome, descrição, parcelas, métodos, recorrência e src. A resposta 201 traz a URL do checkout em data.offer.url. Este gerador monta o comando a partir de um formulário e valida as regras da API antes de você rodar.

O gerador cria o link de verdade?

Não. A ferramenta só monta o comando e o corpo JSON; ela não chama a API e não pede a sua chave. Você copia o curl, o código Node ou Python, e roda no seu terminal ou servidor com o token guardado numa variável de ambiente. No ambiente Sandbox, o link criado é de teste e não aceita pagamento real. Isso é proposital: o token do HeroPay dá acesso à conta e não deve ser digitado em página nenhuma.

Quanto custa criar um link de pagamento no HeroPay?

Criar o link é grátis, sem mensalidade e sem limite de links. Você paga só quando vende: Pix e boleto custam R$ 0 por transação e o cartão custa 3,49% por venda aprovada, em até 12x (tabela de setembro de 2026). Num link de R$ 149, entram R$ 149,00 no Pix e R$ 143,80 no cartão.

Qual o valor mínimo de um link de pagamento?

R$ 5,00, ou price_cents: 500. No cartão parcelado, cada parcela também precisa ter pelo menos R$ 1,99, então um link de R$ 20 aceita no máximo 10x. Se você pedir mais parcelas do que o valor permite, a API responde 422; o gerador calcula o máximo e oferece o ajuste com um clique. O máximo absoluto é 12 parcelas.

O que significa absorbs_fees?

É quem paga os juros quando o comprador parcela no cartão. Com true, você absorve os juros e o comprador vê o preço sem acréscimo, o famoso "12x sem juros". Com false, os juros entram no valor final pago pelo comprador. O campo é obrigatório no POST /payment_links. Ele não muda a tarifa do HeroPay (3,49% no cartão), que é sempre do vendedor; muda só quem paga a taxa de parcelamento de 2,29%. Com false, o repasse ao comprador é automático e você recebe 20% dessa taxa; com true, ela sai do seu lado.

Como criar um link de assinatura?

Mande o campo period com monthly, quarterly, semiannual ou annual. A partir daí o link cobra automaticamente a cada ciclo. Com frequency_type: "unlimited", renova até o cancelamento; com "limited" e frequency_limit, encerra sozinho depois de N cobranças, útil para mentoria de 12 meses. No gerador, escolha "Assinatura" e os campos aparecem. Vendas internacionais valem só para pagamento único.

Como saber de onde veio cada venda do link?

Com o campo src. Mande "src": "whatsapp" na criação e a URL volta com ?src=whatsapp; o valor é salvo no carrinho e entregue em cart.src em todos os webhooks daquela compra, do pagamento confirmado ao chargeback. Aceita letras, números e . _ - ~, até 255 caracteres. O gerador corrige espaços e acentos sozinho e sugere o valor válido.

Posso usar o gerador com Claude, Cursor ou Lovable?

Sim. A aba Prompt transforma o formulário num pedido em português. Cole o llms.txt do HeroPay (heropay.ai/llms.txt) no Claude, ChatGPT, Cursor, Lovable e outros junto com o prompt: com o contrato da API no contexto, a IA monta a mesma chamada ao POST /payment_links. Revise antes de rodar e mantenha o token em variável de ambiente; criar link não mexe no seu saldo. Um MCP server oficial está em desenvolvimento. O passo a passo está em /ai.

Por que o valor vai em centavos?

Porque número inteiro não tem erro de arredondamento. Em ponto flutuante, 0,1 + 0,2 não dá exatamente 0,3, e em pagamento um centavo errado vira divergência de conciliação. Por isso a API do HeroPay recebe e devolve valores em centavos inteiros: R$ 149,00 é 14900. O erro mais comum de integração é mandar 149, que vira R$ 1,49 e é recusado por estar abaixo do mínimo. O gerador faz a conversão e mostra os dois valores.

Gerador de link de pagamento: preencha o formulário, rode o curl, receba a URL