Links de pagamento

Um payment_link (link de pagamento) é uma URL pública hospedada pela Chargefy para vender produtos e serviços sem integrar um formulário de pagamento no seu site. O objeto reúne a oferta, desconto automático, repasse de taxa e URLs de retorno, além de optional_items, template e checkout_experience. Quando o comprador abre o link, a Chargefy resolve seus padrões e exceções e copia a experiência para uma Checkout Session. Apresentação, pós-venda, rastreamento e condições de pagamento ficam estáveis naquela sessão. Marca, suporte e termos continuam vindo da organização. Ele é criado a partir de um conjunto de itens de preço (line_items) e continua no ar 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 pra 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 continua apontando pra 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.*.

{
  "id": "plink_wCUdffpmaJn84rdg",
  "object": "payment_link",
  "allow_discount_codes": false,
  "cancel_url": "https://meusite.com/cancelado",
  "checkout_experience": {
    "banner": null,
    "confirmation_message": null,
    "cover_image_url": null,
    "footer_expanded": false,
    "funnel": null,
    "header_shows_logo": null,
    "installment_teaser_mode": null,
    "order_summary_mode": null,
    "product_description_mode": null,
    "product_image_mode": null,
    "product_subtitle_source": null,
    "require_billing_address": null,
    "require_document": null,
    "require_phone": null,
    "show_compare_at_amount": false,
    "summary_style": null,
    "tracking": {
      "destinations": [],
      "mode": "inherit"
    }
  },
  "created_at": "2026-05-19T18:00:00Z",
  "discount": null,
  "has_surcharge": false,
  "is_active": true,
  "label": "Curso de Programação",
  "line_items": [
    {
      "id": "pli_HEPGLaXVXM3Cmpun",
      "adjustable_quantity": {
        "enabled": false,
        "maximum": null,
        "minimum": null
      },
      "amount_discount": 0,
      "amount_subtotal": 9990,
      "amount_tax": 0,
      "amount_total": 9990,
      "currency": "brl",
      "description": "Mensalidade do Curso",
      "metadata": {},
      "position": 0,
      "price": "price_LqEqLm4dadr3zX5b",
      "price_data": null,
      "product": "prod_YpUzKVs1HsYHzu2w",
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "unit_amount": 9990
    }
  ],
  "livemode": true,
  "metadata": {},
  "optional_items": [],
  "payment_method_collection": "always",
  "payment_method_options": null,
  "payment_method_types": null,
  "subscription_data": {},
  "success_url": "https://meusite.com/sucesso",
  "template": null,
  "updated_at": "2026-05-19T18:00:00Z",
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

string

Identificador único do link de pagamento. Usa o prefixo plink_*.

string

Sempre "payment_link".

boolean

Se o checkout das sessões geradas por este link mostra o campo de código de desconto (e aceita ?prefilled_promo_code=… na URL). Padrão: false.

string | null

A URL para onde o cliente será redirecionado se desistir da compra.

array

Ofertas adicionais na ordem de exibição. Aceitá-las materializa itens de linha com role: "bump"; o cupom alcança somente os itens principais. Os extras são cobrados uma única vez, inclusive durante o trial, e não entram nas renovações.

object

show_compare_at_amount habilita o valor de referência riscado, cadastrado no preço. Padrão false. O estilo offer destaca o produto em uma linha horizontal, com product_subtitle_source escolhendo descrição ou organização na segunda linha. cover_image_url é uma imagem de campanha independente acima do produto; product_image_mode controla somente a imagem do produto. Configuração da página. banner é nulo quando desligado, ou contém variant, text, tone, tag, highlight, ends_at e background_color. O banner é copiado do link na criação da sessão; mudanças posteriores no link não alteram sessões abertas. A mensagem não modifica as condições de cobrança. confirmation_message é a mensagem personalizada exibida após a conclusão da compra, ou null; a sessão conserva o texto do momento de sua criação. funnel é a referência ao funil escolhido, ou null. A sessão conserva essa escolha; após pagamento elegível confirmado, o funil precede success_url. Desativar o funil impede novas ofertas e preserva a compra original. footer_expanded indica se o checkout exibe suporte e termos da organização; é copiado do link na criação da sessão.Apresentação e coleta de dados compartilham o mesmo contrato no link e na sessão. No link, null herda o padrão da organização; na sessão os valores efetivos ficam congelados na criação. Em atualizações, omitir um campo preserva a escolha.

Campo	Valores
`summary_style`	`product`, `subscription`, `offer` ou `null`
`product_image_mode`	`hidden`, `thumbnail`, `hero` ou `null`
`product_subtitle_source`	`description`, `organization` ou `null`; `null` herda o padrão da organização
`cover_image_url`	URL pública de um arquivo `checkout_cover_image` da mesma organização e ambiente; `null` remove a capa
`product_description_mode`	`hidden`, `summary`, `full` ou `null`
`order_summary_mode`	`expanded`, `collapsible`, `compact`, `hidden` ou `null`
`installment_teaser_mode`	`hidden`, `maximum_installment`, `lowest_installment` ou `null`
`header_shows_logo`	Booleano ou `null`
`require_document`, `require_phone`, `require_billing_address`	Booleano ou `null`

Os campos pertencem a checkout_experience. Dados obrigatórios para o meio de pagamento continuam sendo coletados mesmo quando a exigência adicional é false. Cores, fonte e arquivo do logo continuam na marca da organização.

string

Data de criação em formato ISO 8601.

string | null

ID do desconto (dsct_*) fixado no link de pagamento, se houver.

boolean

Se true, o comprador cobre a taxa da organização: o total é acrescido do repasse para que a organização receba líquido o valor da venda. Veja Repassar a tarifa de venda ao comprador. Padrão: false.

boolean

Define se o link de pagamento está ativo e aceitando novas transações.

string | null

Rótulo amigável/título exibido no topo da página de checkout.

array

Lista de itens de preço que compõem o valor cobrado neste link.

Mostrar Campos de line_items[]

string

Identificador único do item do link.

object

Configuração de quantidade ajustável no checkout.

Mostrar Campos de adjustable_quantity

boolean

Se o comprador pode alterar a quantidade no checkout.

integer | null

Maior quantidade permitida, ou null quando não há limite máximo.

integer | null

Menor quantidade permitida, ou null quando não há limite mínimo.

integer

Descontos calculados para o item.

integer

Subtotal do item (unit_amount * quantity).

integer

Impostos calculados para o item.

integer

Total líquido do item em centavos.

string

Moeda, como brl.

string | null

Descrição do item exibida no checkout.

object

Metadados associados a este item.

integer

Ordem/posição do item no checkout.

string | null

ID do preço (price_*) associado.

object | null

Dados inline de preço caso não seja usado um preço salvo.

string | null

ID do produto (prod_*) associado.

integer

Quantidade do item fixada no link.

string | null

Intervalo de recorrência se for assinatura. Vem null em itens de compra única.

Valor	Descrição
`day`	Cobrança diária.
`week`	Cobrança semanal.
`month`	Cobrança mensal.
`year`	Cobrança anual.

integer | null

Multiplicador do intervalo de recorrência.

integer

Valor unitário do item em centavos.

boolean

true se gerado em produção; false se em testes.

object

Metadados customizados vinculados ao link. Retorna {} quando vazio.

string

Quando o checkout deve coletar um método de pagamento em links recorrentes. Pode ser "always" ou "if_required".

object | null

Exceção da oferta sobre quem paga o juro do parcelamento no cartão, em credit_card.installments.interest_payer: buyer acrescenta o juro ao total das parcelas; organization mantém o total igual ao valor à vista, e o juro é descontado do líquido da organização. null (padrão) = sem exceção — cada clique herda a configuração de checkout da organização, inclusive quando ela muda depois. Pagamento à vista nunca tem juro.

object

Configurações aplicadas à assinatura criada por um link recorrente. Sem configuração adicional, retorna o objeto vazio {}.

string | null

A URL para onde o cliente será redirecionado após o pagamento ser concluído com sucesso.

string | null

Exceção de estrutura por oferta: split, sidebar ou stacked. null significa herdar a configuração efetiva da organização. A URL é a mesma para qualquer estrutura. A sessão conserva o template resolvido na sua criação; mudanças no link valem para sessões futuras.

string | null

Data da última atualização em formato ISO 8601.

string

A URL pública compartilhável do checkout hospedado da Chargefy.

Operações

Eventos

Mudanças nesse objeto disparam os seguintes eventos:

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

object

mode indica inherit, custom ou disabled; destinations contém as referências de destinos selecionados. No link, as referências representam suas escolhas explícitas. Na sessão, representam a seleção efetiva congelada na criação. Desativar um destino na organização continua interrompendo seus envios.

integer | null

Limite de parcelas. No link, null herda a organização; na sessão, é o limite resolvido e congelado na criação. interest_payer também pode ser null no link quando apenas o limite é personalizado.

array | null

Meios de pagamento configurados neste link. null herda a organização; uma lista usa exatamente os meios escolhidos.

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Links de pagamento

Objeto payment_link

Operações

Eventos

​Objeto payment_link

​Operações

​Eventos

Objeto payment_link

Operações

Eventos