> ## Documentation Index > Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Diferença entre Link de pagamento vs. Sessão de checkout > Compare Payment Links e Checkout Sessions, entenda a relação entre os dois e escolha qual usar em cada fluxo de venda. **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. ```mermaid theme={"theme":"css-variables"} flowchart LR PL["Payment Link
molde reutilizável"] -->|"acesso do comprador A"| CSA["Checkout Session A
tentativa única"] PL -->|"acesso do comprador B"| CSB["Checkout Session B
tentativa única"] PL -->|"acesso do comprador C"| CSC["Checkout Session C
tentativa única"] API["Seu backend"] -->|"criação via API"| CSD["Checkout Session D
tentativa única"] ``` ## 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: Crie o link pelo Dashboard ou com `POST /v1/payment-links`. A resposta traz a URL pública no campo `url`. Publique em uma landing page, bio de rede social, mensagem, e-mail, QR code ou botão de compra. A Chargefy copia a configuração vigente do link para uma sessão nova, com identidade, prazo e estados próprios. 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](/payments/configure-checkout-page) 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: 1. seu backend envia `POST /v1/checkout-sessions` para criar uma compra individualizada; 2. 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 Ela recebe `status: "open"`, uma `url`, um `client_secret` e um `expires_at` 24 horas depois da criação. A Chargefy apresenta itens, total, dados necessários e métodos habilitados na organização. 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. 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: 1. **A oferta será compartilhada pela mesma URL?** Use Payment Link. 2. **Já existe um pedido no seu sistema?** Crie uma Checkout Session e grave o ID do pedido em `metadata`. 3. **Itens, comprador ou retorno mudam por tentativa?** Use Checkout Session. 4. **Você não quer manter um endpoint para iniciar cada compra?** Use Payment Link. 5. **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 ```bash theme={"theme":"css-variables"} 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 ```bash theme={"theme":"css-variables"} 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 Um link pode originar muitas sessões. Ele identifica a oferta, não uma venda individual. Correlacione o pedido com a Checkout Session correspondente. Se cada link só será usado uma vez, você está recriando manualmente o papel da Checkout Session e acumulando links administrativos sem necessidade. `complete` e `expired` são estados terminais. Uma nova tentativa exige uma nova sessão. 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. 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 Veja configuração, atualização, desativação, metadata e atribuição. Veja estados, expiração, customer, métodos, confirmação e webhooks. Consulte o contrato completo e as variantes de `line_items`. Consulte todos os campos para individualizar uma tentativa.