Skip to main content
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 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 compraO 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

ObjetoResponsabilidadeTempo de vida
payment_linkFixa line_items + config de checkout numa URL compartilhávelPermanente enquanto is_active = true
checkout.sessionUma tentativa de compra materializada a partir do linkEfê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 LinkCheckout Session
ReutilizávelSim — uma URL, N comprasNão — uma tentativa de compra
Quando criarUma vez, na configuração da ofertaA cada pedido, via API
Liga a um pedido específicoNãoSim (via metadata)
Ideal paraBotão “comprar agora”, campanha, link em mensagemFluxo 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

1

Você cria o payment link

Define os line_items e a configuração de checkout (cupom, endereço, parcelamento, URLs de retorno, metadata). A resposta traz o campo url.
2

Você compartilha a URL

O mesmo link serve em site, campanha, mensagem direta ou QR code. Compartilhe sempre o campo url retornado — nunca componha a URL manualmente.
3

O comprador abre o link

A Chargefy materializa uma checkout.session copiando line_items e metadata, e redireciona para o checkout hospedado.
4

O comprador paga no checkout

O checkout hospedado coleta os dados, confirma o pagamento e atualiza os status da sessão.
5

Você recebe webhooks

Acompanhe o ciclo da sessão por checkout.session.* para liberar o produto ou atualizar seu sistema.
CampoTipoDescrição
urlstringURL pública pra compartilhar. Cada clique materializa uma sessão.
line_itemsarrayItens fixados no link. Cada sessão copia 1:1 (veja line_items).
labelstring | nullNome interno do link, visível só pra organização. Nunca aparece pro comprador.
allow_discount_codesbooleanSe o comprador pode inserir cupom no checkout. Default true.
discount_idstring | nullDesconto aplicado automaticamente em todas as sessões geradas.
require_billing_addressbooleanQuando true, endereço de cobrança é obrigatório. Default herdado da organização. Boleto sempre exige.
require_documentbooleanQuando true, documento (CPF/CNPJ) é obrigatório. Default herdado da organização (true). Boleto sempre exige.
require_phonebooleanQuando true, telefone do comprador é obrigatório. Default herdado da organização (false).
payment_method_optionsobjectOpçõ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_urlstring | nullDestino do comprador após pagamento aprovado.
cancel_urlstring | nullDestino se o comprador cancelar ou abandonar.
is_activebooleanfalse para de gerar sessões novas, sem afetar as já materializadas.
metadataobjectPares chave→valor livres, controlados por você. Copiados pra cada sessão.
O schema público completo está em Objeto payment_link. Crie pela API com POST /v1/payment-links. Só line_items é obrigatório; o resto da configuração tem defaults sensatos. 
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 }
    ]
  }'
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).
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. 
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. 
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. 
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.

​
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.
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"
    }
  }'
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:
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:
EventoQuando
payment.link.createdO link é criado.
payment.link.updatedO 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.
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

Objeto payment_link

Schema público completo e campos retornados.

Criar payment link (API)

Contrato do POST /v1/payment-links com as três variantes de line_items.

Checkout Sessions

O que cada clique materializa e como acompanhar o pagamento.

Produtos e preços

Modele o catálogo que alimenta os line_items.