Criar um Link de pagamento

Um Link de pagamento é uma URL pública e reutilizável de venda. Você configura uma oferta uma vez, compartilha o endereço e recebe quantas compras forem necessárias. Cada acesso cria uma Checkout Session nova e independente. Use quando a mesma oferta puder ser vendida por mensagem, e-mail, rede social, QR Code ou botão de compra sem que o seu backend precise criar uma sessão para cada comprador.

O Link de pagamento não é a compraO link é o molde reutilizável da oferta. Cada comprador que abre a URL gera uma Checkout Session própria, com dados, prazo, status e pagamento independentes. Mil acessos ao mesmo link podem gerar mil sessões diferentes.

Para cobrar uma fatura existente, use invoice.hosted_invoice_url. Essa URL pertence a uma única invoice e continua mostrando a fatura depois do pagamento ou cancelamento. Links de pagamento são para ofertas reutilizáveis que criam Checkout Sessions novas.

Antes de começar

No Dashboard, cada item pode usar um preço já cadastrado ou um preço personalizado criado somente para aquele link. O preço define se o link cobra uma única vez ou inicia uma assinatura.

O que você quer vender	Como configurar
Produto ou serviço avulso	Use um preço de cobrança única.
Plano, mensalidade ou acesso contínuo	Use um preço recorrente; o pagamento aprovado inicia uma assinatura.
Dois ou mais produtos na mesma compra	Clique em Adicionar item e configure cada produto, preço e quantidade.
Valor exclusivo sem criar preço no catálogo	Escolha Preço personalizado e use um produto existente ou informe um novo.
Quantidade escolhida pelo comprador	Ative a quantidade ajustável e defina os limites mínimo e máximo daquele item.

O comprador pode alterar a quantidade quando essa opção estiver ativa, mas não digita livremente quanto quer pagar.

Todos os itens do mesmo link usam a mesma moeda e o mesmo tipo de cobrança. Em assinaturas, todos também usam a mesma recorrência. Por exemplo, dois produtos mensais podem ficar no mesmo link; um mensal e outro anual precisam de links separados.

Para criar pela API, você também precisa de uma API key do ambiente test ou live. Mantenha essa credencial somente no backend.

Você pode criar e testar o link antes da ativação financeira da organização. Em produção, o pagamento só será aceito depois que a organização estiver apta a receber.

Criar pelo Dashboard

Abrir Links de pagamento

Entre no Dashboard, escolha a organização e abra Links de pagamento.

Dashboard da Chargefy na página Links de pagamento, mostrando filtros, links ativos e o botão Novo link de pagamento — Lista de Links de pagamento no Dashboard, com filtros, ações rápidas e acesso à criação de um novo link.

Abra Links de pagamento

No Dashboard, escolha a organização e acesse Links de pagamento. Clique em Novo link de pagamento.

Escolha o que será vendido

Use um preço do catálogo ou escolha Preço personalizado. Defina a quantidade e, se necessário, os limites que o comprador pode ajustar. Para vender mais produtos juntos, clique em Adicionar item e repita.

Configure o link

Em Preço, defina itens, descontos, meios de pagamento, parcelas e até três order bumps. Página de pagamento reúne estrutura, informações exibidas, dados solicitados, banner e rodapé. Depois do pagamento define confirmação, redirecionamento e funil. Tracking permite herdar, personalizar ou desativar destinos. Em assinaturas, configure também trial e coleta da forma de pagamento.

Crie e compartilhe

Clique em Criar link de pagamento. Na página do link, copie a URL ou gere o QR Code para compartilhar com os compradores.

Os padrões vêm do Checkout Builder e podem ser personalizados no link. Cada acesso cria uma sessão com a experiência e as condições de pagamento daquele momento. Alterações posteriores no link não afetam sessões abertas. Marca, suporte e termos são da organização.

Para reutilizar uma configuração, abra o link e escolha Mais ações → Duplicar link. Revise a cópia nas quatro abas e clique em Criar link de pagamento. Itens, bumps e configurações acompanham a cópia; o link original e seu histórico permanecem independentes.

Como o link gera compras

Momento	Recurso	Resultado
Configuração da oferta	`payment_link`	Cria um molde reutilizável com URL pública.
Cada clique	Nova `checkout.session`	Copia itens, desconto, URLs e metadata para uma tentativa independente.
Comprador paga	Sessão correspondente	Conclui o pagamento daquela tentativa.
Comprador abandona	Sessão correspondente	A sessão expira sem afetar o link nem as outras sessões.

Objeto	Responsabilidade	Tempo de vida
payment_link	Fixa `line_items` + config de checkout numa URL compartilhável	Permanente enquanto `is_active = true`
checkout.session	Uma tentativa de compra materializada a partir do link	Efêmera — nasce no clique, expira ou conclui

A cada acesso à URL, a Chargefy copia os line_items e o metadata do link para uma sessão nova, emite checkout.session.created e redireciona o comprador para o checkout hospedado. As sessões são independentes do link: desativar o link não afeta sessões já materializadas.

Se itens, comprador ou URLs de retorno mudarem em cada pedido, crie uma Checkout Session diretamente. Veja Link de pagamento vs. Sessão de checkout.

Anatomia do link

Campo	Tipo	Descrição
`url`	`string`	URL pública pra compartilhar. Cada clique materializa uma sessão.
`line_items`	`array`	Um ou mais itens fixados no link. Cada sessão copia todos eles (veja line_items).
`label`	`string \| null`	Nome interno do link, visível só pra organização. Nunca aparece pro comprador.
`discount_id`	`string \| null`	Desconto aplicado automaticamente em todas as sessões geradas.
`allow_discount_codes`	`boolean`	Se o checkout deste link mostra o campo de código de desconto.
`has_surcharge`	`boolean`	Se o comprador cobre a taxa da organização.
`success_url`	`string \| null`	Destino do comprador após pagamento aprovado.
`cancel_url`	`string \| null`	Destino se o comprador cancelar ou abandonar.
`is_active`	`boolean`	`false` para de gerar sessões novas, sem afetar as já materializadas.
`metadata`	`object`	Pares chave→valor livres, controlados por você. Copiados pra cada sessão.

O schema público completo está em Objeto payment_link. A aparência e o comportamento da página são definidos na marca e no Checkout Builder da organização, não no objeto do link.

Criar pela API

Crie pela API com POST /v1/payment-links. Só line_items é obrigatório; o resto da configuração tem defaults sensatos.

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "price_id": "price_NNohJatWveK4T1An", "quantity": 1 }
    ]
  }'

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Bio do Instagram - Plano Pro",
    "line_items": [
      { "price_id": "price_NNohJatWveK4T1An", "quantity": 1 }
    ],
    "success_url": "https://meusite.com/obrigado",
    "metadata": {}
  }'

A resposta inclui o campo url. Essa é a URL que você compartilha.

line_items

Cada item aponta para um preço do catálogo (price_id) ou descreve um preço inline (price_data) — exatamente um dos dois. Três formas válidas, da mais idiomática à mais ad-hoc.

Restrições aplicadas a todo o array: todos os itens usam a mesma currency; e ou todos são recorrentes ou nenhum é (não pode misturar recorrente com cobrança única no mesmo link). Em links recorrentes, todos também usam o mesmo interval e interval_count, porque entram na mesma assinatura.

(a) Preço do catálogo

Caminho mais curto. Resolve produto, valor e recorrência automaticamente a partir do price_id. Quando o preço referenciado é recurring, as sessões geradas nascem em modo subscription sem nenhum campo extra.

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "price_id": "price_NNohJatWveK4T1An", "quantity": 1 }
    ]
  }'

(b) Produto do catálogo + preço ad-hoc

Reusa nome e descrição do produto cadastrado, mas com um valor único pra esse link. Útil pra promoção pontual sem criar preço novo no catálogo. Adicione recurring em price_data para tornar o item recorrente.

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_data": {
          "currency": "brl",
          "product_id": "prod_WHkKz2YESCEWnNWK",
          "unit_amount": 12990
        },
        "quantity": 1
      }
    ]
  }'

(c) Produto e preço ad-hoc

Nada vem do catálogo — útil pra integrações headless que não cadastram produto.

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_data": {
          "currency": "brl",
          "product_data": {
            "description": "Sessão de 1h por videoconferência",
            "name": "Consultoria avulsa"
          },
          "unit_amount": 4990
        },
        "quantity": 1
      }
    ]
  }'

O contrato completo de cada variante, com os campos de price_data e recurring, está em Criar link de pagamento.

Compartilhar o link

O mesmo endereço pode ser compartilhado quantas vezes forem necessárias e em mais de um canal ao mesmo tempo. Cada pessoa que o abre recebe uma Checkout Session independente.

Copiar no Dashboard ou na API

Na lista de Links de pagamento, use a ação de copiar ao lado do link. Você também pode abrir a página de detalhe, copiar a URL exibida no topo ou abrir o checkout em uma nova aba para revisá-lo antes de publicar. Quando o link é criado pela API, compartilhe o campo url da resposta. Não compartilhe a URL de uma Checkout Session gerada a partir dele: essa sessão é temporária e pertence a uma única tentativa de compra.

Escolher onde publicar

Canal	Como usar
Mensagens e e-mail	Cole a URL diretamente na conversa ou campanha.
Redes sociais	Use a URL em biografias, publicações e anúncios.
Site ou landing page	Aponte o botão de compra para a URL do link.
QR Code	Gere e baixe a imagem na página de detalhe do Dashboard.

Usar em um botão do seu site

Qualquer botão ou link do seu site pode abrir a URL hospedada pela Chargefy. O exemplo abaixo usa um link HTML comum:

<a href="{{PAYMENT_LINK_URL}}">Comprar agora</a>

Você pode reutilizar a mesma URL em diferentes botões. Para identificar de onde veio cada acesso, acrescente parâmetros de campanha ou use o rastreamento descrito em Metadata e atribuição.

Gerar um QR Code

Abra a página de detalhe do link e clique em QR Code. Você pode copiar a imagem ou baixar o arquivo PNG para usar em materiais impressos, balcões, eventos ou embalagens. O QR Code aponta para a URL do link e não expira por conta própria. Se você editar a oferta, ele continua levando aos dados atuais do mesmo link. Se o link for desativado, novos acessos deixam de abrir o checkout; ao reativá-lo, o mesmo QR Code volta a funcionar.

Antes de divulgar, abra o link em uma nova aba e confira produto, valor, quantidade, métodos de pagamento, campos solicitados e página de retorno. Faça uma compra no ambiente de teste para validar também o evento usado na entrega do produto.

Metadata e atribuição

O metadata do link é copiado para cada sessão gerada. Use-o para correlacionar a venda com entidades do seu sistema, como um ID interno ou a versão da oferta. Parâmetros de campanha anexados à URL são capturados separadamente como atribuição da checkout session criada naquele clique:

{{PAYMENT_LINK_URL}}?utm_source=meta&utm_medium=paid_social&utm_campaign=lancamento&fbclid=click_123

A captura aceita:

utm_id, utm_source, utm_medium, utm_campaign, utm_term e utm_content;
utm_source_platform, utm_creative_format e utm_marketing_tactic;
fbclid, gclid, gbraid, wbraid, ttclid e msclkid;
fbc e fbp, quando sua integração já dispõe desses identificadores.

Para capturar a campanha na página do seu site e propagar os parâmetros automaticamente até o link, use Chargefy.Checkout.trackLinks().

A atribuição não é mesclada em metadata. O primeiro snapshot normalizado aparece em marketing_attribution na checkout session criada e nos webhooks checkout.session.*. Pré-preenchimento de e-mail, cupom e idioma tem transporte próprio — veja Parâmetros de URL.

curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [{ "price_id": "price_NNohJatWveK4T1An", "quantity": 1 }],
    "metadata": {}
  }'

Parâmetros de URL

Além da atribuição de campanha, a URL do link aceita parâmetros de pré-preenchimento e contexto. Eles valem para aquele compartilhamento: o mesmo link circula em quantas variações de URL você quiser, e cada clique absorve os parâmetros na checkout session criada.

{{PAYMENT_LINK_URL}}?prefilled_email=nome%40email.com&prefilled_promo_code=BEMVINDO20&locale=pt-BR&client_reference_id=pedido%3A2026%2F8412

Parâmetro	O que faz	Formato
`prefilled_email`	Preenche o e-mail do comprador no checkout; ele ainda pode editar.	E-mail válido, de preferência URL-encoded.
`locked_prefilled_email`	Preenche e trava o e-mail: o campo aparece somente leitura e o confirm ignora outro valor. Tem precedência sobre `prefilled_email`.	E-mail válido, de preferência URL-encoded.
`prefilled_promo_code`	Aplica o código de desconto automaticamente ao abrir o checkout. Só tem efeito com `allow_discount_codes` ativo no link.	Letras, números, `-` e `_`; maiúsculas e minúsculas valem igual.
`locale`	Define o idioma da página de checkout.	`pt-BR` ou `en-US`; os atalhos `pt` e `en` valem.
`client_reference_id`	Anexa uma referência sua à sessão criada — um ID de pedido ou de carrinho, por exemplo. O valor volta no objeto da sessão e nos webhooks `checkout.session.*` para conciliação com seu sistema.	De 1 a 200 caracteres imprimíveis. Use URL encoding; controles e quebras de linha são ignorados.

Valor inválido é descartado em silêncio e a página continua funcionando normalmente — um parâmetro malformado nunca quebra o checkout.

Parâmetros ficam visíveis na URL. Não coloque segredos em client_reference_id e compartilhe URLs com prefilled_email ou locked_prefilled_email somente com o destinatário certo.

Atualizar um link

O update é merge via POST /v1/payment-links/{id}: você envia só os campos que mudam. Dá para editar label, URLs de retorno, discount_id, allow_discount_codes, has_surcharge, template, metadata, is_active e substituir os line_items inteiros.

Reenviar line_items substitui o conjunto inteiro — os itens antigos são arquivados e os novos passam a valer. Sessões já materializadas mantêm os itens que copiaram no momento do clique; só os cliques futuros usam a nova configuração.

Marca, estrutura, estilo do resumo e modos de exibição são lidos ao abrir a página. Métodos, campos obrigatórios e parcelamento permanecem fixados na criação da sessão. No link, template: null herda o padrão efetivo da organização; uma estrutura explícita vale somente para a oferta. Trocar a estrutura não altera URLs; sessões existentes passam a exibir a escolha atual sem mudar valores, parcelas ou meios de pagamento.

Desativar e remover

DELETE /v1/payment-links/{id} expressa “tirar de circulação”. O efeito depende do histórico:

Link que nunca gerou sessão

É removido de fato. A resposta é { "id": "plink_Ps4zFCbVKhBwMoeJ", "object": "payment_link", "deleted": true }.

Link que já materializou sessões

Não pode sumir sem quebrar histórico, então é desativado (is_active = false) e a resposta é o objeto completo atualizado. Novos cliques na URL passam a retornar 404; as sessões já materializadas seguem vivas e independentes.

Você também pode desativar diretamente com POST /v1/payment-links/{id} enviando is_active: false, sem tentar a remoção.

Eventos de webhook

O próprio objeto payment_link dispara:

Evento	Quando
`payment.link.created`	O link é criado.
`payment.link.updated`	O link é atualizado ou desativado. `data.previous_attributes` traz os campos alterados.

Cada clique no link materializa uma sessão e dispara checkout.session.created. Daí em diante, acompanhe o ciclo da sessão — não do link — para liberar produto e conciliar pagamento. Esses eventos estão documentados em Checkout Sessions.

Compartilhe sempre o campo url retornado ao criar o link. A URL da checkout session gerada a partir dele é temporária e pode expirar — ela serve só para aquela tentativa de compra.

Próximos passos

Objeto payment_link

Schema público completo e campos retornados.

Criar via API

Contrato do POST /v1/payment-links com as três variantes de line_items.

Entender Checkout Sessions

O que cada clique materializa e como acompanhar o pagamento.

Após receber com um Link de pagamento

Confirme o resultado, entregue o produto e cuide da experiência pós-compra.

Produtos, preços e descontos

Modele o catálogo que alimenta os line_items.

Pagamentos online

Receber pagamentos

Clientes e faturamento

Assinaturas

Operação e pós-pagamento

Marketing e rastreamento

Criar um Link de pagamento

Antes de começar

Criar pelo Dashboard

Abrir Links de pagamento

Como o link gera compras

Anatomia do link

Criar pela API

line_items

(a) Preço do catálogo

(b) Produto do catálogo + preço ad-hoc

(c) Produto e preço ad-hoc

Compartilhar o link

Copiar no Dashboard ou na API

Escolher onde publicar

Usar em um botão do seu site

Gerar um QR Code

Metadata e atribuição

Parâmetros de URL

Atualizar um link

Desativar e remover

Eventos de webhook

Próximos passos

Objeto payment_link

Criar via API

Entender Checkout Sessions

Após receber com um Link de pagamento

Produtos, preços e descontos

​Antes de começar

​Criar pelo Dashboard

Abrir Links de pagamento

​Como o link gera compras

​Anatomia do link

​Criar pela API

​line_items

​(a) Preço do catálogo

​(b) Produto do catálogo + preço ad-hoc

​(c) Produto e preço ad-hoc

​Compartilhar o link

​Copiar no Dashboard ou na API

​Escolher onde publicar

​Usar em um botão do seu site

​Gerar um QR Code

​Metadata e atribuição

​Parâmetros de URL

​Atualizar um link

​Desativar e remover

​Eventos de webhook

​Próximos passos

Objeto payment_link

Criar via API

Entender Checkout Sessions

Após receber com um Link de pagamento

Produtos, preços e descontos

Antes de começar

Criar pelo Dashboard

Como o link gera compras

Anatomia do link

Criar pela API

line_items

(a) Preço do catálogo

(b) Produto do catálogo + preço ad-hoc

(c) Produto e preço ad-hoc

Compartilhar o link

Copiar no Dashboard ou na API

Escolher onde publicar

Usar em um botão do seu site

Gerar um QR Code

Metadata e atribuição

Parâmetros de URL

Atualizar um link

Desativar e remover

Eventos de webhook

Próximos passos