Diferença entre Link de pagamento vs. Sessão de checkout

Payment Link e Checkout Session abrem a mesma experiência de checkout, mas resolvem momentos diferentes da venda:

o Payment Link é um molde público e reutilizável de uma oferta;
a Checkout Session representa uma compra específica, com itens, valores, descontos, dados do comprador, prazo e resultado próprios.

O ponto mais importante é que eles não são alternativas no mesmo nível. Quando alguém abre um Payment Link, a Chargefy cria uma Checkout Session nova. Portanto, a decisão é quem deve criar cada compra: a Chargefy, automaticamente a partir de um link reutilizável, ou o seu backend, pela API e com os parâmetros próprios daquele pedido.

Regra rápida: use Payment Link quando várias pessoas puderem comprar a mesma oferta pela mesma URL. Use Checkout Session quando cada pedido precisar nascer com dados próprios.

Comparação completa

Critério	Payment Link	Checkout Session
O que representa	Uma oferta reutilizável.	Uma tentativa específica de compra.
Relação entre os objetos	Um link pode originar quantas sessões forem necessárias.	Cada sessão pertence a uma única tentativa, tenha sido criada pela API ou por um link.
Quem cria	Você cria o link uma vez pelo Dashboard ou pela API.	Seu backend cria pela API; alternativamente, a Chargefy cria automaticamente quando alguém abre um Payment Link.
Quando nasce	Quando você publica/configura a oferta.	Quando um comprador abre o link ou quando seu backend inicia o pedido.
URL	Pública, estável e feita para ser compartilhada.	Única e temporária, feita para aquela tentativa.
Reutilização	A mesma URL atende muitos compradores e compras.	Não é reutilizável depois de concluída ou expirada.
Validade	Não expira enquanto estiver ativo.	Expira 24 horas depois de criada.
Estados principais	`is_active: true` ou `false`. O link não fica “pago”.	`status: open`, `complete` ou `expired`, além de `payment_status`.
Itens e valores	Define a oferta-base que será copiada para cada nova sessão.	Define os itens e valores daquela compra.
Carrinho dinâmico	Não é indicado quando cada pedido tem uma composição diferente.	É o caminho indicado para carrinhos, orçamentos e pedidos calculados sob demanda.
Comprador conhecido	Não fixa um customer no link; a URL compartilhada pode pré-preencher o e-mail (`prefilled_email` ou `locked_prefilled_email`).	Pode ser vinculada a um customer existente ou receber dados de pré-preenchimento no create.
Pré-preenchimento pela URL	Aceita `prefilled_email`, `locked_prefilled_email`, `prefilled_promo_code`, `locale` e `client_reference_id` na URL, por compartilhamento.	Recebe os mesmos dados como campos do create; a URL da sessão aceita apenas `locale`.
Correlação com seu pedido	O `metadata` do link é copiado para todas as sessões futuras; para identificar um pedido único, anexe `client_reference_id` à URL compartilhada.	Pode receber `metadata` exclusivo e `client_reference_id` no create para correlacionar a sessão ao seu sistema.
URLs de retorno	Usa a mesma configuração de retorno para as sessões futuras, até o link ser editado.	Pode ter `success_url` e `cancel_url` próprias por pedido.
Atribuição de campanha	Recebe UTMs e identificadores de clique pela URL; a sessão criada registra o primeiro toque.	Pode receber atribuição pela URL ou o objeto `marketing_attribution` no momento da criação.
Experiência no navegador	Abre o checkout hospedado.	Entrega `url` para o checkout hospedado e `client_secret` para o runtime do browser.
Alterações	Mudanças no link afetam somente sessões criadas depois da edição.	A compra já nasce com seu próprio snapshot de itens, valores e dados.
Desativação ou encerramento	Pode ser desativado; sessões já criadas continuam independentes.	Pode ser expirada enquanto estiver aberta; depois disso, crie outra sessão.
Webhooks do próprio recurso	`payment.link.created` e `payment.link.updated`.	`checkout.session.created`, `completed`, `expired` e eventos assíncronos de pagamento.
Fonte para liberar o produto	Nunca use o estado do link; acompanhe a sessão criada e o resultado financeiro.	Use webhooks e confirme `payment_status`; não confie apenas no redirecionamento do comprador.
Melhor encaixe	Campanhas, redes sociais, mensagens, QR codes e botões de compra de oferta fixa.	E-commerce, SaaS, reservas, pedidos individualizados e fluxos controlados pelo backend.
Backend para iniciar cada compra	Não é necessário.	Necessário quando a sessão é criada diretamente pela API.

A escolha não depende de ser pagamento avulso ou assinatura. Os dois podem vender itens únicos ou recorrentes. O que muda é se a oferta deve ser reutilizável ou se cada tentativa precisa ser individualizada.

O que é um Payment Link

Um Payment Link é uma URL pública que guarda a configuração de uma oferta. Você define os itens, o desconto automático, o comportamento de coleta, o repasse de tarifa quando aplicável, as URLs de retorno e o metadata. Enquanto o link estiver ativo, você pode compartilhá-lo quantas vezes quiser. Ele funciona como um molde:

Você configura a oferta uma vez

Crie o link pelo Dashboard ou com POST /v1/payment-links. A resposta traz a URL pública no campo url.

Você compartilha a mesma URL

Publique em uma landing page, bio de rede social, mensagem, e-mail, QR code ou botão de compra.

Cada acesso cria uma Checkout Session

A Chargefy copia a configuração vigente do link para uma sessão nova, com identidade, prazo e estados próprios.

Cada comprador segue um ciclo independente

Uma pessoa pode pagar, outra abandonar e uma terceira tentar mais tarde sem que uma sessão altere as demais ou o próprio link.

O que fica no link

O link mantém a configuração que deve ser repetida nas compras futuras:

line_items, com preço de catálogo ou valor ad-hoc;
discount, quando todas as sessões devem começar com o mesmo desconto;
has_surcharge, para repasse de tarifa em cobrança avulsa;
payment_method_collection e subscription_data, em ofertas recorrentes;
success_url e cancel_url;
metadata, copiado para cada sessão criada;
label, usado internamente para identificar o link;
is_active, que controla se novos acessos ainda podem gerar sessões.

A identidade visual, os métodos de pagamento, os campos exigidos e o parcelamento não ficam duplicados no link. Eles vêm da configuração atual do Checkout Builder da organização.

O que não fica no link

Um Payment Link não representa:

um comprador específico;
um pedido individual do seu sistema;
uma tentativa de pagamento;
um status paid ou unpaid;
uma confirmação de que produto ou acesso pode ser liberado.

Essas informações pertencem à Checkout Session e aos objetos financeiros criados durante a compra.

O que acontece quando o link é editado

Editar itens, desconto, URLs ou metadata muda o molde para os próximos acessos. Sessões que já foram criadas preservam o snapshot que receberam e não são reescritas. Se o link for desativado, ele deixa de criar sessões novas. As sessões já materializadas continuam com seu próprio ciclo até concluir ou expirar. Isso preserva o histórico de compradores que já iniciaram o checkout.

Quando usar Payment Link

Use quando a resposta para estas perguntas for “sim”:

muitas pessoas podem comprar a mesma oferta;
a URL precisa continuar válida por tempo indeterminado;
a compra começa fora do seu produto, como em mensagem, campanha ou QR code;
você quer começar sem implementar uma rota no backend para cada clique;
os itens, o desconto e o destino após a compra podem ser compartilhados;
a identidade do comprador pode ser coletada no próprio checkout.

Exemplos adequados:

um plano mensal divulgado na bio de uma rede social;
uma consultoria avulsa vendida por mensagem;
um ingresso de valor fixo divulgado por QR code;
um botão “Comprar agora” para uma oferta única em uma landing page;
uma campanha de e-mail em que todos recebem a mesma oferta.

Quando não usar Payment Link

Não use como atalho para uma venda que já tem identidade própria. Prefira uma Checkout Session quando:

cada comprador tem carrinho, preço, cupom ou prazo diferente;
sua aplicação já criou um pedido e precisa ligar a tentativa a ele;
você precisa travar a sessão em um customer existente;
as URLs de retorno mudam por pedido;
seu backend precisa enviar atribuição de marketing antes de abrir a página;
a compra exige invoice_creation em pagamento avulso;
o navegador precisa operar a sessão pelo client_secret.

Para cobrar uma invoice já existente, não crie um Payment Link. Compartilhe a hosted_invoice_url da própria invoice, que continua ligada àquela cobrança.

O que é uma Checkout Session

Uma Checkout Session é o contexto de uma única tentativa de compra. Ela reúne os itens, o total, o comprador conhecido ou pré-preenchido, as URLs de retorno, o prazo e os estados daquela tentativa. Ela pode nascer de duas formas:

seu backend envia POST /v1/checkout-sessions para criar uma compra individualizada;
um comprador abre um Payment Link e a Chargefy materializa a sessão automaticamente.

Em ambos os casos, o objeto resultante segue o mesmo ciclo.

Ciclo de vida da sessão

A sessão nasce aberta

Ela recebe status: "open", uma url, um client_secret e um expires_at 24 horas depois da criação.

O comprador abre o checkout

A Chargefy apresenta itens, total, dados necessários e métodos habilitados na organização.

O comprador confirma

A sessão passa para complete. Em cartão, o pagamento normalmente é resolvido na hora; em PIX ou boleto, a compensação pode acontecer depois.

Seu backend acompanha o resultado

Webhooks informam quando a tentativa foi concluída, expirou ou teve o pagamento assíncrono confirmado.

Se ninguém confirmar dentro de 24 horas, a sessão passa para expired. Uma sessão concluída ou expirada é terminal: ela não volta para open. Para uma nova tentativa, crie outra sessão ou deixe o comprador abrir novamente o Payment Link de origem.

Dois estados que não devem ser confundidos

A sessão separa a conclusão do formulário do resultado financeiro:

Campo	Valor	Significado
`status`	`open`	O comprador ainda pode concluir o checkout.
`status`	`complete`	O comprador terminou o fluxo. Não significa necessariamente que o dinheiro compensou.
`status`	`expired`	A janela de 24 horas terminou sem confirmação.
`payment_status`	`unpaid`	O pagamento ainda não foi confirmado.
`payment_status`	`paid`	O pagamento foi confirmado.
`payment_status`	`no_payment_required`	O total é zero e não há valor a cobrar.

Uma sessão de PIX ou boleto pode estar complete e unpaid: o comprador já recebeu as instruções, mas o dinheiro ainda não compensou. Libere o produto somente depois do webhook de pagamento confirmado.

O que você consegue individualizar

Ao criar diretamente pela API, cada sessão pode receber:

itens e quantidades daquele carrinho;
preço de catálogo ou preço ad-hoc;
customer existente ou dados de pré-preenchimento;
desconto, URLs de retorno e metadata do pedido;
atribuição de marketing já conhecida pelo backend;
comportamento de assinatura e trial;
criação de invoice para uma venda avulsa, quando aplicável;
tipo semântico do botão, como pagar, assinar, reservar ou doar.

O metadata é o caminho recomendado para correlacionar a sessão ao seu pedido. Ele é ecoado nos webhooks da sessão, permitindo que seu backend encontre o registro correto sem interpretar IDs internos da Chargefy.

`url` e `client_secret`

A criação direta devolve dois caminhos para o navegador:

Campo	Use quando	Observação
`url`	Você quer redirecionar para a página hospedada.	É única e expira com a sessão.
`client_secret`	Seu frontend precisa consultar e confirmar a sessão pelo runtime público.	Pode ir ao browser; sua API key não pode.

Quando usar Checkout Session

Use quando a resposta para qualquer uma destas perguntas for “sim”:

existe um pedido, carrinho, orçamento ou reserva no seu sistema;
itens, quantidades ou valores mudam por comprador;
você precisa evitar duplicidade com uma chave de idempotência;
a sessão precisa ficar vinculada a um customer conhecido;
o retorno deve levar para uma página específica daquele pedido;
você precisa enviar um identificador próprio em metadata;
seu backend decide o momento exato em que a tentativa deve nascer;
seu frontend usa o client_secret para operar a experiência;
você precisa expirar uma tentativa aberta antes das 24 horas.

Exemplos adequados:

checkout de e-commerce com carrinho dinâmico;
upgrade de plano calculado para uma conta específica;
reserva com preço, datas e adicionais próprios;
orçamento B2B aprovado e convertido em cobrança;
pedido criado no seu sistema antes do redirecionamento;
assinatura com trial ou prazo definido para aquele contrato.

Quando não usar Checkout Session direta

Criar uma sessão por API adiciona uma etapa de backend. Evite esse trabalho quando você só precisa divulgar uma oferta fixa para muitas pessoas. Nesse caso, o Payment Link já cria uma sessão independente por acesso e continua oferecendo o mesmo checkout, webhooks e rastreabilidade da tentativa.

O que os dois têm em comum

Payment Link e Checkout Session compartilham várias capacidades. Portanto, estas características não devem decidir sozinhas entre eles:

pagamento avulso ou assinatura;
preço de catálogo ou preço ad-hoc;
cartão, PIX e boleto, conforme a configuração da organização;
desconto pré-aplicado;
repasse de tarifa em cobrança avulsa;
ajuste de quantidade dentro de uma faixa configurada;
checkout hospedado com a identidade da organização;
captura de UTMs e identificadores de clique pela URL;
acompanhamento do resultado por webhooks.

A diferença permanece a mesma: o Payment Link repete uma oferta; a Checkout Session individualiza uma tentativa.

Como decidir

Siga esta ordem:

A oferta será compartilhada pela mesma URL? Use Payment Link.
Já existe um pedido no seu sistema? Crie uma Checkout Session e grave o ID do pedido em metadata.
Itens, comprador ou retorno mudam por tentativa? Use Checkout Session.
Você não quer manter um endpoint para iniciar cada compra? Use Payment Link.
Ainda está em dúvida? Comece pela Checkout Session se o seu produto já possui backend e pedidos; ela preserva a relação um-para-um desde o início.

Cenário	Escolha	Motivo
Bio, WhatsApp, campanha ou QR code	Payment Link	A mesma URL precisa criar compras independentes para muitas pessoas.
Landing page com uma oferta fixa	Payment Link	O catálogo da oferta muda pouco e não existe pedido antes do clique.
Carrinho de e-commerce	Checkout Session	Itens, quantidades e total pertencem a um pedido específico.
Compra iniciada dentro de um SaaS	Checkout Session	A sessão precisa se correlacionar à conta e à ação do usuário.
Reserva ou orçamento personalizado	Checkout Session	Dados e valor variam por tentativa.
Assinatura pública com o mesmo plano	Payment Link	Recorrência não exige sessão direta quando a oferta é igual para todos.
Assinatura negociada por cliente	Checkout Session	Trial, prazo ou correlação podem variar por contrato.
Cobrança de invoice existente	URL da invoice	A cobrança já existe; não crie outro objeto de venda.
Cobrança server-to-server com cartão salvo	Payment Intent	Não há necessidade de abrir uma experiência de checkout.

Exemplo mínimo de cada caminho

Criar um Payment Link uma vez

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

Guarde e compartilhe o campo url retornado. Não crie outro link para cada comprador; cada acesso já materializa uma Checkout Session independente.

Criar uma Checkout Session por pedido

curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-order-8f4c2a" \
  -d '{
    "line_items": [
      {
        "price_id": "price_NNohJatWveK4T1An",
        "quantity": 1
      }
    ],
    "metadata": {},
    "success_url": "https://meusite.com/pedido/confirmado?session_id={CHECKOUT_SESSION_ID}"
  }'

Crie no backend, associe a sessão ao pedido do seu sistema e redirecione o comprador para o campo url. A Idempotency-Key evita sessões duplicadas em retries da mesma operação.

Acompanhar o resultado corretamente

Em ambos os caminhos, o Payment Link só inicia a jornada. O resultado confiável vive na sessão e nos objetos financeiros relacionados.

Evento	O que significa	Ação típica
`payment.link.created`	O molde reutilizável foi criado.	Registrar ou exibir o link.
`payment.link.updated`	A configuração ou disponibilidade do link mudou.	Sincronizar o estado administrativo.
`checkout.session.created`	Uma tentativa individual nasceu.	Relacionar a tentativa ao seu contexto.
`checkout.session.completed`	O comprador terminou o checkout.	Verificar `payment_status`; não presumir compensação assíncrona.
`checkout.session.async.payment.succeeded`	PIX ou boleto foi compensado.	Liberar produto de forma idempotente.
`checkout.session.async.payment.failed`	A tentativa assíncrona falhou ou expirou.	Manter o pedido pendente/falhado e oferecer nova tentativa.
`checkout.session.expired`	A janela da sessão terminou.	Criar outra sessão se o comprador quiser tentar de novo.

O redirecionamento para success_url ajuda a experiência do comprador, mas não é prova de pagamento. Use webhooks assinados e processe cada efeito uma única vez.

Erros de modelagem comuns

Usar um Payment Link como ID de pedido

Um link pode originar muitas sessões. Ele identifica a oferta, não uma venda individual. Correlacione o pedido com a Checkout Session correspondente.

Criar um Payment Link novo para cada comprador

Se cada link só será usado uma vez, você está recriando manualmente o papel da Checkout Session e acumulando links administrativos sem necessidade.

Reaproveitar uma Checkout Session concluída

complete e expired são estados terminais. Uma nova tentativa exige uma nova sessão.

Liberar o pedido quando o checkout redireciona

O comprador pode fechar a página, repetir a navegação ou usar um método assíncrono. O webhook é a fonte confiável do resultado.

Escolher pelo tipo de cobrança

Tanto Payment Link quanto Checkout Session aceitam venda avulsa e assinatura. Escolha pela reutilização da oferta e pela individualização do pedido.

Próximos passos

Entender Payment Links

Veja configuração, atualização, desativação, metadata e atribuição.

Entender Checkout Sessions

Veja estados, expiração, customer, métodos, confirmação e webhooks.

Criar um Payment Link

Consulte o contrato completo e as variantes de line_items.

Criar uma Checkout Session

Consulte todos os campos para individualizar uma tentativa.

Pagamentos online

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Diferença entre Link de pagamento vs. Sessão de checkout

Comparação completa

O que é um Payment Link

O que fica no link

O que não fica no link

O que acontece quando o link é editado

Quando usar Payment Link

Quando não usar Payment Link

O que é uma Checkout Session

Ciclo de vida da sessão

Dois estados que não devem ser confundidos

O que você consegue individualizar

`url` e `client_secret`

Quando usar Checkout Session

Quando não usar Checkout Session direta

O que os dois têm em comum

Como decidir

Exemplo mínimo de cada caminho

Criar um Payment Link uma vez

Criar uma Checkout Session por pedido

Acompanhar o resultado corretamente

Erros de modelagem comuns

Próximos passos

Entender Payment Links

Entender Checkout Sessions

Criar um Payment Link

Criar uma Checkout Session

​Comparação completa

​O que é um Payment Link

​O que fica no link

​O que não fica no link

​O que acontece quando o link é editado

​Quando usar Payment Link

​Quando não usar Payment Link

​O que é uma Checkout Session

​Ciclo de vida da sessão

​Dois estados que não devem ser confundidos

​O que você consegue individualizar

​url e client_secret

​Quando usar Checkout Session

​Quando não usar Checkout Session direta

​O que os dois têm em comum

​Como decidir

​Exemplo mínimo de cada caminho

​Criar um Payment Link uma vez

​Criar uma Checkout Session por pedido

​Acompanhar o resultado corretamente

​Erros de modelagem comuns

​Próximos passos

Entender Payment Links

Entender Checkout Sessions

Criar um Payment Link

Criar uma Checkout Session

Comparação completa

O que é um Payment Link

O que fica no link

O que não fica no link

O que acontece quando o link é editado

Quando usar Payment Link

Quando não usar Payment Link

O que é uma Checkout Session

Ciclo de vida da sessão

Dois estados que não devem ser confundidos

O que você consegue individualizar

`url` e `client_secret`

Quando usar Checkout Session

Quando não usar Checkout Session direta

O que os dois têm em comum

Como decidir

Exemplo mínimo de cada caminho

Criar um Payment Link uma vez

Criar uma Checkout Session por pedido

Acompanhar o resultado corretamente

Erros de modelagem comuns

Próximos passos