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

Para criar pelo Dashboard, você precisa ter pelo menos um produto com preço cadastrado. 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.
Mais de uma unidade do mesmo item	Ative a quantidade ajustável e defina os limites para o comprador.

O valor sempre parte de um preço configurado por você. O comprador pode alterar a quantidade quando essa opção estiver ativa, mas não digita livremente quanto quer pagar. 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

Selecione um produto ou assinatura do catálogo e defina a quantidade inicial. Se necessário, permita que o comprador ajuste essa quantidade no checkout.

Configure o link

Defina o nome interno, desconto pré-aplicado, aceitação de códigos de desconto, repasse de tarifa e URLs de sucesso ou cancelamento. Em links recorrentes, você também pode configurar avaliação gratuita.

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.

Tela Criar link de pagamento preenchida com uma consultoria e sua prévia de checkout em desktop — Criação de um Link de pagamento com produto, quantidade e configurações ao lado da prévia do checkout.

Cores, fonte, métodos de pagamento, campos obrigatórios, parcelamento e template vêm da configuração atual da organização no Checkout Builder.

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`	Itens fixados no link. Cada sessão copia 1:1 (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 no Checkout Builder, 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).

(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_8412

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.	Até 200 caracteres com letras, números, `-` e `_`.

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, 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.

Alterações no Checkout Builder são diferentes: por serem configuração da organização, passam a valer também para links e sessões já abertos no próximo carregamento.

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

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

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