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

# Overview

> O objeto Payment Link

Um `payment_link` (link de pagamento) é uma página de checkout pública hospedada pela Chargefy que permite vender produtos e serviços de forma rápida e segura sem precisar integrar um formulário de pagamento no seu próprio site. Ele centraliza as regras de negócio do checkout — como exigência de endereço, telefone ou documento do comprador, permissão para cupons de desconto, parcelamento sem juros e URLs de redirecionamento após a conclusão ou cancelamento.

Ele é criado dinamicamente a partir de um conjunto de itens de preço (`line_items`) e permanece ativo enquanto `is_active` for `true`. Qualquer pessoa com acesso à URL do link pode preencher os dados de pagamento e concluir a compra, o que gera uma `checkout_session` correspondente para cada tentativa de finalização.

Payment links não representam faturas existentes. Para cobrar ou exibir uma invoice já criada, use `invoice.hosted_invoice_url`, que pertence a uma única invoice e permanece apontando para ela depois do pagamento ou cancelamento.

## Objeto payment\_link

Este é o formato completo retornado em `create`, `get`, `update`, itens de `list` e em `data.object` dos webhooks `payment.link.*`.

```json theme={}
{
  "id": "plink_123",
  "object": "payment_link",
  "allow_discount_codes": true,
  "cancel_url": "https://example.com/cancel",
  "created_at": "2026-05-19T18:00:00Z",
  "discount": null,
  "is_active": true,
  "label": "Curso de Programação",
  "line_items": [
    {
      "id": "pli_123",
      "amount_discount": 0,
      "amount_subtotal": 9990,
      "amount_tax": 0,
      "amount_total": 9990,
      "currency": "brl",
      "description": "Mensalidade do Curso",
      "metadata": {},
      "position": 0,
      "price": "price_123",
      "price_data": null,
      "product": "prod_123",
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "unit_amount": 9990
    }
  ],
  "livemode": true,
  "metadata": {},
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "has_interest": true,
        "max_count": 12
      }
    }
  },
  "require_billing_address": false,
  "require_document": true,
  "require_phone": true,
  "success_url": "https://example.com/success",
  "updated_at": "2026-05-19T18:00:00Z",
  "url": "https://pay.chargefy.io/l/plink_123_abc"
}
```

<ResponseField name="id" type="string">
  Identificador único do link de pagamento. Usa o prefixo `plink_*`.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"payment_link"`.
</ResponseField>

<ResponseField name="allow_discount_codes" type="boolean">
  Define se cupons de desconto podem ser aplicados pelo comprador na página do checkout.
</ResponseField>

<ResponseField name="cancel_url" type="string | null">
  A URL para onde o cliente será redirecionado se desistir da compra.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação em formato ISO 8601.
</ResponseField>

<ResponseField name="discount" type="string | null">
  ID do desconto (`dsct_*`) fixado no link de pagamento, se houver.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Define se o link de pagamento está ativo e aceitando novas transações.
</ResponseField>

<ResponseField name="label" type="string | null">
  Rótulo amigável/título exibido no topo da página de checkout.
</ResponseField>

<ResponseField name="line_items" type="array">
  Lista de itens de preço que compõem o valor cobrado neste link.

  <Expandable title="Campos de line_items[]">
    <ResponseField name="id" type="string">Identificador único do item do link.</ResponseField>
    <ResponseField name="amount_discount" type="integer">Descontos calculados para o item.</ResponseField>
    <ResponseField name="amount_subtotal" type="integer">Subtotal do item (`unit_amount * quantity`).</ResponseField>
    <ResponseField name="amount_tax" type="integer">Impostos calculados para o item.</ResponseField>
    <ResponseField name="amount_total" type="integer">Total líquido do item em centavos.</ResponseField>
    <ResponseField name="currency" type="string">Moeda, como `brl`.</ResponseField>
    <ResponseField name="description" type="string | null">Descrição do item exibida no checkout.</ResponseField>
    <ResponseField name="metadata" type="object">Metadados associados a este item.</ResponseField>
    <ResponseField name="position" type="integer">Ordem/posição do item no checkout.</ResponseField>
    <ResponseField name="price" type="string | null">ID do preço (`price_*`) associado.</ResponseField>
    <ResponseField name="price_data" type="object | null">Dados inline de preço caso não seja usado um preço salvo.</ResponseField>
    <ResponseField name="product" type="string | null">ID do produto (`prod_*`) associado.</ResponseField>
    <ResponseField name="quantity" type="integer">Quantidade do item fixada no link.</ResponseField>
    <ResponseField name="recurring_interval" type="string | null">Intervalo de recorrência se for assinatura (`day`, `week`, `month`, `year`).</ResponseField>
    <ResponseField name="recurring_interval_count" type="integer | null">Multiplicador do intervalo de recorrência.</ResponseField>
    <ResponseField name="unit_amount" type="integer">Valor unitário do item em centavos.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` se gerado em produção; `false` se em testes.
</ResponseField>

<ResponseField name="metadata" type="object">
  Metadados customizados vinculados ao link. Retorna `{}` quando vazio.
</ResponseField>

<ResponseField name="payment_method_options" type="object">
  Opções por método de pagamento oferecidas no checkout.

  <Expandable title="Campos de payment_method_options">
    <ResponseField name="credit_card" type="object">
      Opções do cartão de crédito.

      <Expandable title="Campos de credit_card">
        <ResponseField name="installments" type="object">
          Configuração do parcelamento.

          <Expandable title="Campos de installments">
            <ResponseField name="has_interest" type="boolean">
              `true` quando o comprador paga o acréscimo do parcelamento;
              `false` quando o lojista absorve o acréscimo.
            </ResponseField>

            <ResponseField name="max_count" type="integer">
              Número máximo de parcelas oferecidas (1–12).
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="require_billing_address" type="boolean">
  Se `true`, exige que o comprador preencha um endereço de cobrança completo.
</ResponseField>

<ResponseField name="require_document" type="boolean">
  Se `true`, exige o preenchimento de CPF ou CNPJ pelo comprador.
</ResponseField>

<ResponseField name="require_phone" type="boolean">
  Se `true`, exige o preenchimento do telefone de contato do comprador.
</ResponseField>

<ResponseField name="success_url" type="string | null">
  A URL para onde o cliente será redirecionado após o pagamento ser concluído com sucesso.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Data da última atualização em formato ISO 8601.
</ResponseField>

<ResponseField name="url" type="string">
  A URL pública compartilhável do checkout hospedado da Chargefy.
</ResponseField>

## Operações

* [Criar link de pagamento](/api-reference/payment-links/create)
* [Consultar link de pagamento](/api-reference/payment-links/get)
* [Atualizar link de pagamento](/api-reference/payment-links/update)
* [Listar links de pagamento](/api-reference/payment-links/list)
* [Desativar link de pagamento](/api-reference/payment-links/delete)

## Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook:

* [`payment.link.created`](/api-reference/webhooks/payment.link.created)
* [`payment.link.updated`](/api-reference/webhooks/payment.link.updated)

O payload carrega o objeto `payment_link` completo em `data.object`.