Pular para o conteúdo principal
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. A moeda do link é definida na criação, aparece em currency e vale para todas as sessões abertas por ele. Para vender em outra moeda habilitada, crie outro link. Este é o formato completo retornado em create, get, update, itens de list e em data.object dos webhooks payment.link.*.
string
obrigatório
Escolha da oferta: inherit aceita indicação por cupom ou clique, explicit usa a lista definida e none desliga a indicação automática. affiliates continua trazendo a divisão efetivamente registrada.
array
obrigatório
Condições de comissão de afiliado registradas: cada item contém affiliation e affiliate_fee_rate em pontos-base; [] indica ausência de comissão de afiliado. Esta seleção não comprova recebimento: o pagamento registra o resultado de cada participante. Encerrar uma parceria retira sua participação nas próximas cobranças e preserva os valores e as parcelas já divididos.
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. Cada oferta traz currency, a moeda do preço da oferta, ao lado de compare_at_amount, que está nessa moeda.
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, duration_minutes, duration_seconds, 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. success_redirect informa quando o comprador segue para a success_url: { "delay_seconds": 10, "type": "automatic" } redireciona ao fim da contagem, delay_seconds: 0 leva direto do checkout sem a confirmação, e { "delay_seconds": null, "type": "manual" } espera o clique em Continuar. null segue o padrão da organizaçã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.Por exemplo, show_phone: true com require_phone: false exibe WhatsApp opcional. Com os dois em true, o comprador precisa preenchê-lo. Com os dois em false, o campo fica oculto. Campos obrigatórios continuam visíveis, mesmo com show_*: false.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
Moeda definida na criação do link. As sessões abertas pelo link usam essa moeda.
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.
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.