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

# Criar um Link de pagamento

> Crie uma URL reutilizável para vender produtos ou assinaturas pelo Dashboard ou pela API e compartilhe com seus compradores.

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](/payments/create-checkout-page) 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.

<Info>
  **O Link de pagamento não é a compra**

  O 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.
</Info>

<Note>
  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.
</Note>

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

<Tip>
  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.
</Tip>

## Criar pelo Dashboard

<Card title="Abrir Links de pagamento" icon="arrow-up-right-from-square" href="https://app.chargefy.io">
  Entre no Dashboard, escolha a organização e abra **Links de pagamento**.
</Card>

<Frame caption="Lista de Links de pagamento no Dashboard, com filtros, ações rápidas e acesso à criação de um novo link.">
  <img src="https://mintcdn.com/scaleup-28315a31/KoGyPnB0fzTxgiXL/assets/payments/checkout/create-payment-link/payment-links-list.jpg?fit=max&auto=format&n=KoGyPnB0fzTxgiXL&q=85&s=e67dc5b697031f492b4a4176d74074f7" alt="Dashboard da Chargefy na página Links de pagamento, mostrando filtros, links ativos e o botão Novo link de pagamento" width="1280" height="720" data-path="assets/payments/checkout/create-payment-link/payment-links-list.jpg" />
</Frame>

<Steps>
  <Step title="Abra Links de pagamento">
    No Dashboard, escolha a organização e acesse **Links de pagamento**. Clique
    em **Novo link de pagamento**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Frame caption="Criação de um Link de pagamento com produto, quantidade e configurações ao lado da prévia do checkout.">
  <img src="https://mintcdn.com/scaleup-28315a31/KoGyPnB0fzTxgiXL/assets/payments/checkout/create-payment-link/create-payment-link.jpg?fit=max&auto=format&n=KoGyPnB0fzTxgiXL&q=85&s=6493cce69607206f6e23b81e03f316f2" alt="Tela Criar link de pagamento preenchida com uma consultoria e sua prévia de checkout em desktop" width="1280" height="720" data-path="assets/payments/checkout/create-payment-link/create-payment-link.jpg" />
</Frame>

<Info>
  Cores, fonte, métodos de pagamento, campos obrigatórios, parcelamento e
  template vêm da configuração atual da organização no [Checkout
  Builder](/payments/configure-checkout-page).
</Info>

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

<Tip>
  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](/payments/payment-link-vs-checkout-session).
</Tip>

## 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.  |
| `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](/api-reference/payment-links).
A aparência e o comportamento da página são definidos no
[Checkout Builder](/payments/configure-checkout-page), 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.

<CodeGroup>
  ```bash Mínimo 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 }
      ]
    }'
  ```

  ```bash Com retorno e correlação 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 '{
      "label": "Bio do Instagram - Plano Pro",
      "line_items": [
        { "price_id": "price_NNohJatWveK4T1An", "quantity": 1 }
      ],
      "success_url": "https://meusite.com/obrigado",
      "metadata": {}
    }'
  ```
</CodeGroup>

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.

<Info>
  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).
</Info>

### (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={"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 }
    ]
  }'
```

### (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={"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_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.

```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_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](/api-reference/payment-links/create).

## 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:

```html theme={"theme":"css-variables"}
<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](#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.

<Tip>
  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.
</Tip>

## 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:

```text theme={"theme":"css-variables"}
{{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.

<Tip>
  Para capturar a campanha na página do seu site e propagar os parâmetros
  automaticamente até o link, use
  [`Chargefy.Checkout.trackLinks()`](/api/chargefy-js).
</Tip>

<Note>
  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](#parâmetros-de-url).
</Note>

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

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

```text theme={"theme":"css-variables"}
{{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.

<Warning>
  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.
</Warning>

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

<Note>
  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.
</Note>

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:

<AccordionGroup>
  <Accordion title="Link que nunca gerou sessão">
    É removido de fato. A resposta é `{ "id": "plink_Ps4zFCbVKhBwMoeJ", "object": "payment_link", "deleted": true }`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

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](/payments/create-checkout-page).

<Tip>
  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.
</Tip>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Objeto payment_link" icon="link" href="/api-reference/payment-links">
    Schema público completo e campos retornados.
  </Card>

  <Card title="Criar via API" icon="code" href="/api-reference/payment-links/create">
    Contrato do `POST /v1/payment-links` com as três variantes de `line_items`.
  </Card>

  <Card title="Entender Checkout Sessions" icon="cart-shopping" href="/payments/create-checkout-page">
    O que cada clique materializa e como acompanhar o pagamento.
  </Card>

  <Card title="Após receber com um Link de pagamento" icon="circle-check" href="/payments/payment-link-post-payment">
    Confirme o resultado, entregue o produto e cuide da experiência pós-compra.
  </Card>

  <Card title="Produtos, preços e descontos" icon="cube" href="/products-prices-discounts/overview">
    Modele o catálogo que alimenta os `line_items`.
  </Card>
</CardGroup>