Links de pagamento
Atualizar um link de pagamento
Atualiza um payment link.
O valor de cada item e a soma de preço × quantidade devem caber em o teto da moeda (
A alteração de
A partir desse momento, novos cliques abrem checkout com o novo preço. Cliques anteriores (sessões já criadas) seguem com o preço antigo até concluírem ou expirarem.
Sessões já abertas mantêm o tempo com que foram criadas.
999999999 na menor unidade em brl), antes de descontos e juros. Valores acima retornam 400 amount_too_large, com param indicando o campo ou a coleção de itens.
Atualiza campos de um payment link. Só os campos enviados são alterados — o resto fica como estava.
Importante: atualizações afetam apenas cliques futuros. Sessões já materializadas a partir de cliques anteriores guardam os line_items que tinham no momento do clique — é cópia, não referência. Trocar o preço hoje não muda nada do que já está em cobrança; só novos cliques a partir de agora veem o novo preço.
Os novos itens precisam usar a moeda gravada no link. currency pode ser informada apenas na criação.
Autenticação
Mesmo contrato de POST /v1/payment-links — Org API key (write ou admin) ou API key da plataforma (platform_admin) com header Organization.
Parâmetros de caminho
Attributes
Todos os campos são opcionais. Apenas o que for enviado é atualizado.null aceita a indicação por cupom válido ou pelo último clique válido de uma afiliada. Omitir na criação também aceita indicação; omitir na atualização preserva a escolha atual. [] desliga a indicação e uma lista define os afiliados explicitamente.Comissões de afiliados para vínculos ativos: cada item contém affiliation (aff_*) e
affiliate_fee_rate, inteiro de 1 a 10000 pontos-base (3000 = 30%).
Os percentuais incidem em paralelo sobre o valor líquido da venda antes das
comissões de afiliados; a soma não pode ultrapassar 10000. Até 8 afiliados em venda
direta ou 7 com plataforma. Envie [] para remover a seleção.
Veja Comissões de afiliados.affiliates no link vale para novas sessões. Sessões, assinaturas e faturas anteriores preservam o combinado registrado.
Liga ou desliga o campo de código de desconto no checkout deste link. Vale
para cliques futuros; sessões já materializadas mantêm a configuração do
momento do clique. Valor que não seja booleano retorna
400.Até três ofertas adicionais, sempre avulsas e desmarcadas. A ordem do array define a posição. Cada item recebe
price, title e call_to_action; aceita description, tag (recommended, special_offer ou null), product_name, image (arquivo com propósito order_bump_image) e compare_at_amount (em centavos, a menor unidade da moeda, maior que o preço). Todos os preços e arquivos devem pertencer à organização e ao ambiente da compra. O preço deve usar a mesma moeda dos itens principais. Lista vazia remove as ofertas; omissão preserva o valor atual na atualização. Para preservar a identidade de uma oferta e apenas editar ou reordenar, envie seu id.Configuração da página. Omitir um campo preserva sua configuração;
banner: null desliga o banner. checkout_experience: null restaura a herança da apresentação, coleta e trackeamento, limpa a capa, a descrição personalizada e a mensagem de confirmação, remove o funil, volta o redirecionamento ao padrão da organização e desliga o banner, o rodapé expandido e a ancoragem de preç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.Liga ou desliga o repasse de taxa. Vale para cliques futuros; sessões já
materializadas mantêm a configuração do momento do clique. O repasse vale só
para cobrança avulsa: não pode ser ligado num link de assinatura, e os itens
de um link com repasse não podem ser trocados por itens recorrentes — as duas
direções retornam
400.Envie
false para desativar o link. Cliques futuros retornam 404; sessões já
materializadas continuam vivas. Envie true para reativar.Substitui completamente os line items do link. Mesma forma de envio do
POST. Os antigos são arquivados
(cliques futuros não os enxergam mais); sessões já materializadas mantêm os
antigos. Todos os itens precisam compartilhar moeda e tipo de cobrança; quando
recorrentes, também precisam ter o mesmo
interval e interval_count.Substitui o objeto inteiro. Pra preservar chaves existentes, busque o link
primeiro e envie o merge.
Mesma semântica do POST. Trocar os
itens de recorrente para avulso derruba este campo de volta para
always.Troca quem paga o juro do parcelamento
(
credit_card.installments.interest_payer: buyer ou organization).
null limpa a exceção — o link
volta a herdar a configuração de checkout da organização. Vale para cliques
futuros; sessões já materializadas mantêm o snapshot do clique, e
assinaturas já criadas conservam a política da venda.Substitui o objeto inteiro. Mesma forma de envio do
POST. Trocar os itens de recorrente
para avulso limpa a configuração, porque não haveria assinatura para
configurar.
Omitir preserva a escolha atual; enviar
null remove a exceção. Estrutura de página única: split, sidebar ou stacked.
null herda a configuração efetiva da organização, incluindo o padrão da
plataforma que a controla. A estrutura é resolvida ao abrir a página, inclusive em sessões
existentes. A URL e as condições financeiras das sessões permanecem iguais.Resposta
200 OK com o objeto canônico do payment link. Mesma forma da resposta de POST /v1/payment-links.
Webhook
Quando a chamada altera algum campo, a Chargefy emitepayment.link.updated.
O webhook segue o payload padrão: data.object carrega o payment link completo
já atualizado, e data.previous_attributes carrega apenas os campos alterados
com o valor anterior.
Trocar o preço de um link
cURL
Fixar quando o comprador volta
O link passa a usar o próprio tempo, mesmo que a organização mude o padrão:cURL
Voltar a seguir o padrão da organização
Comnull, o link volta a usar o tempo de Configurações → Pagamentos → Checkout:
cURL
Erros comuns
Define os destinos de conversão desta experiência.
mode aceita inherit (padrões da organização), custom (somente destinations) ou disabled (nenhum envio). custom exige de 1 a 50 IDs de destinos ativos da mesma organização e ambiente; os outros modos usam uma lista vazia. null restaura a herança e a ausência preserva a configuração. A sessão congela a seleção ao ser criada. Não envie tokens de acesso neste campo.Máximo de parcelas oferecido ao comprador, entre 1 e 12;
1 permite somente pagamento à vista. A elegibilidade do valor e da recorrência pode reduzir esse limite. null restaura o padrão da organização. Omitir preserva a escolha atual; atualizar somente este campo preserva interest_payer e vice-versa. A sessão guarda o limite resolvido na criação.Meios oferecidos no checkout:
credit_card, pix e boleto. Envie uma lista não vazia, sem repetições; a ordem da lista é a ordem em que o comprador vê os meios, e o primeiro já vem selecionado. null herda a organização; omitir em uma atualização preserva a escolha. Novas sessões guardam os meios efetivos na criação.
