> ## 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. # Payment Links > Uma URL pública e reutilizável que materializa uma checkout session a cada clique. Um **payment link** é uma URL pública e reutilizável de venda. Você configura a oferta uma vez — o que será vendido (`line_items`) e como o checkout se comporta (cupom, endereço de cobrança, parcelamento, URLs de retorno) — compartilha a URL, e a Chargefy materializa uma [checkout session](/features/checkout-sessions) nova a cada clique. O link é o **molde**; cada sessão é uma **instância** dele. Use payment links quando quiser vender sem criar uma sessão via API para cada comprador: bio do Instagram, e-mail marketing, QR code, botão de "comprar agora" numa landing page ou link no WhatsApp. **O payment link não é a compra** O link é reutilizável e permanente enquanto `is_active = true`. Cada comprador que abre a URL gera uma checkout session própria, com dados, status e pagamento independentes. Mil cliques no mesmo link geram mil sessões distintas. 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. Payment links são para ofertas reutilizáveis que criam checkout sessions novas. ## Modelo conceitual ```mermaid theme={} flowchart LR PL[payment_link
molde reutilizável] -- cada clique --> CS1[checkout.session #1] PL -- cada clique --> CS2[checkout.session #2] PL -- cada clique --> CS3[checkout.session #3] CS1 -. paga .-> P1[payment] CS2 -. abandonada .-> X[expira] CS3 -. paga .-> P3[payment] ``` | 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. ## Payment Link vs Checkout Session | | Payment Link | Checkout Session | | --------------------------- | ------------------------------------------------- | ----------------------------------------------- | | Reutilizável | Sim — uma URL, N compras | Não — uma tentativa de compra | | Quando criar | Uma vez, na configuração da oferta | A cada pedido, via API | | Liga a um pedido específico | Não | Sim (via `metadata`) | | Ideal para | Botão "comprar agora", campanha, link em mensagem | Fluxo programático ligado a `metadata.order_id` | Na prática: * botão "comprar agora" no site → **payment link**; * cobrança que seu backend cria para o pedido `id_123` → **checkout session**; * campanha com a mesma oferta para milhares de pessoas → **payment link**; * fluxo totalmente programático e individualizado → **checkout session**. ## Como funciona Define os `line_items` e a configuração de checkout (cupom, endereço, parcelamento, URLs de retorno, metadata). A resposta traz o campo `url`. O mesmo link serve em site, campanha, mensagem direta ou QR code. Compartilhe sempre o campo `url` retornado — nunca componha a URL manualmente. A Chargefy materializa uma `checkout.session` copiando `line_items` e `metadata`, e redireciona para o checkout hospedado. O checkout hospedado coleta os dados, confirma o pagamento e atualiza os status da sessão. Acompanhe o ciclo da sessão por `checkout.session.*` para liberar o produto ou atualizar seu sistema. ## 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](#line-items)). | | `label` | `string \| null` | Nome interno do link, visível só pra organização. Nunca aparece pro comprador. | | `allow_discount_codes` | `boolean` | Se o comprador pode inserir cupom no checkout. Default `true`. | | `discount_id` | `string \| null` | Desconto aplicado automaticamente em todas as sessões geradas. | | `require_billing_address` | `boolean` | Quando `true`, endereço de cobrança é obrigatório. Default herdado da organização. Boleto sempre exige. | | `require_document` | `boolean` | Quando `true`, documento (CPF/CNPJ) é obrigatório. Default herdado da organização (`true`). Boleto sempre exige. | | `require_phone` | `boolean` | Quando `true`, telefone do comprador é obrigatório. Default herdado da organização (`false`). | | `payment_method_options` | `object` | Opções por método de pagamento. `credit_card.installments.has_interest` (boolean) define se o comprador paga o acréscimo do parcelamento; `credit_card.installments.max_count` (integer 1–12) é o número máximo de parcelas. Quando omitido, aplicam-se os padrões 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](/api-reference/payment-links). ## Criar um payment link Crie pela API com `POST /v1/payment-links`. Só `line_items` é obrigatório; o resto da configuração tem defaults sensatos. ```bash Mínimo theme={} 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_789", "quantity": 1 } ] }' ``` ```bash Com config de checkout theme={} 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_789", "quantity": 1 } ], "allow_discount_codes": true, "require_billing_address": false, "require_document": true, "require_phone": false, "payment_method_options": { "credit_card": { "installments": { "has_interest": false, "max_count": 12 } } }, "success_url": "https://meusite.com/obrigado", "metadata": { "campaign": "black-friday" } }' ``` 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. ```bash theme={} 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_789", "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. ```bash theme={} 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_456", "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. ```bash theme={} 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 payment link](/api-reference/payment-links/create). ## Metadata e prefill O `metadata` do link é **copiado para cada sessão gerada**. É o canal canônico pra correlacionar uma venda com o seu sistema (campanha, origem, ID interno). Parâmetros de URL anexados ao link (`utm_*`, `customer_email`, `discount_code`, etc.) **não** são mesclados na sessão automaticamente. Só o `metadata` configurado no próprio link é copiado. Se precisa guardar rastreamento, coloque essas chaves no `metadata` ao criar ou atualizar o link. ```bash theme={} 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_789", "quantity": 1 }], "metadata": { "campaign": "black-friday", "source": "instagram_bio" } }' ``` ## Atualizar um link O update é **merge** via `POST /v1/payment-links/{id}`: você envia só os campos que mudam. Dá pra editar `label`, as URLs de retorno, as flags de checkout (`allow_discount_codes`, `require_billing_address`, `require_document`, `require_phone`), o `payment_method_options`, `discount_id`, `metadata`, `is_active` e até 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. ## Desativar e remover `DELETE /v1/payment-links/{id}` expressa "tirar de circulação". O efeito depende do histórico: É removido de fato. A resposta é `{ "id": "plink_123", "object": "payment_link", "deleted": true }`. 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`](/api-reference/webhooks/payment.link.created) | O link é criado. | | [`payment.link.updated`](/api-reference/webhooks/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](/features/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 Schema público completo e campos retornados. Contrato do `POST /v1/payment-links` com as três variantes de `line_items`. O que cada clique materializa e como acompanhar o pagamento. Modele o catálogo que alimenta os `line_items`.