Atualizar um link de pagamento

curl -X POST "https://api.chargefy.io/v1/payment-links/plink_HTFCXiiJFWgEdqH5" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Bio Instagram - Atualizado",
    "metadata": {},
    "payment_method_collection": "always",
    "subscription_data": {},
    "success_url": "https://meusite.com/nova-pagina"
  }'

{
  "id": "plink_HTFCXiiJFWgEdqH5",
  "object": "payment_link",
  "allow_discount_codes": false,
  "cancel_url": null,
  "checkout_experience": {
    "banner": null,
    "confirmation_message": null,
    "cover_image_url": null,
    "footer_expanded": false,
    "funnel": null,
    "header_shows_logo": null,
    "header_shows_name": null,
    "installment_teaser_mode": null,
    "order_summary_mode": null,
    "product_description": 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-02T18:31:00Z",
  "discount": null,
  "has_surcharge": false,
  "is_active": true,
  "label": "Bio Instagram - Atualizado",
  "line_items": [],
  "livemode": true,
  "metadata": {},
  "optional_items": [],
  "payment_method_collection": "always",
  "payment_method_options": null,
  "payment_method_types": null,
  "subscription_data": {},
  "success_url": "https://meusite.com/nova-pagina",
  "template": null,
  "updated_at": "2026-05-02T18:35:00Z",
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

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.

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

string

obrigatório

ID do payment link, prefixo plink_.

Attributes

Todos os campos são opcionais. Apenas o que for enviado é atualizado.

boolean

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.

string

Envie null pra remover.

array

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 (centavos, 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.

object | null

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

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`	Texto exclusivo do checkout, até 2.000 caracteres. `null` usa a descrição do produto; `""` não exibe descrição. Não altera o catálogo.
`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`; exibe o avatar
`header_shows_name`	Booleano ou `null`; exibe o nome. Ambos `false` ocultam o cabeçalho; `null` herda o padrão
`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.

Mostrar Configuração da experiência

string | null

Mensagem opcional de até 1.000 caracteres, exibida após a conclusão da compra. Texto vazio ou null remove a mensagem; omitir preserva a configuração. Pix ou boleto ainda pendentes não exibem essa confirmação.

string | null

Funil ativo e pronto da mesma organização e ambiente. null remove a associação; omitir preserva. Sessões criadas diretamente podem reutilizar um funil sem criar link. Cada funil tem no máximo um link de entrada; tentar associá-lo a outro link retorna 409.

boolean

Exibe o preço de referência riscado acima do valor cobrado. Padrão false. O valor vem de compare_at_amount no preço e é congelado na criação da sessão; não altera cobrança, cupons, taxas ou parcelas.

boolean

Exibe suporte e termos cadastrados na organização. Padrão false; false também desliga o rodapé. Não exige aceite do comprador.

object | null

Mensagem de marketing livre, inclusive valores e percentuais. Não altera preço, disponibilidade, prazo da oferta ou pagamento.

Mostrar Campos do banner

string | null

Cor de fundo em hexadecimal de 6 dígitos, como #27272a. null usa o tom escolhido. A cor do texto é ajustada para manter o contraste.

string

obrigatório

strip, highlight, countdown ou marquee.

string

obrigatório

Mensagem entre 1 e 500 caracteres, exibida como texto.

string

padrão:"neutral"

neutral, urgent ou success; usa as cores do design system.

string | null

Etiqueta opcional, até 40 caracteres.

string | null

Trecho em destaque, até 120 caracteres.

integer | null

Duração de 1 a 60 minutos, iniciada quando cada comprador abre o checkout. Atualizar a página no mesmo navegador mantém o tempo restante. Use apenas com countdown, sem ends_at.

integer | null

Segundos adicionais, de 0 a 59, com duration_minutes. Omitir usa zero. A duração total não pode ultrapassar 60 minutos; por exemplo, duration_minutes: 1 e duration_seconds: 30 exibem 01:30.

string | null

Prazo fixo ISO 8601 com fuso horário, como alternativa a duration_minutes. Informe apenas um dos dois para countdown. Ao terminar, somente o banner desaparece.

string

Desconto auto-aplicado. null remove.

boolean

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.

boolean

Envie false para desativar o link. Cliques futuros retornam 404; sessões já materializadas continuam vivas. Envie true para reativar.

string

Nome interno. Envie null pra remover.

array

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.

object

Substitui o objeto inteiro. Pra preservar chaves existentes, busque o link primeiro e envie o merge.

string

Mesma semântica do POST. Trocar os itens de recorrente para avulso derruba este campo de volta para always.

object | null

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.

object

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.

string

Envie null pra remover.

string | null

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.

curl -X POST "https://api.chargefy.io/v1/payment-links/plink_HTFCXiiJFWgEdqH5" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Bio Instagram - Atualizado",
    "metadata": {},
    "payment_method_collection": "always",
    "subscription_data": {},
    "success_url": "https://meusite.com/nova-pagina"
  }'

Resposta

200 OK com o objeto canônico do payment link. Mesma forma da resposta de POST /v1/payment-links.

{
  "id": "plink_HTFCXiiJFWgEdqH5",
  "object": "payment_link",
  "allow_discount_codes": false,
  "cancel_url": null,
  "checkout_experience": {
    "banner": null,
    "confirmation_message": null,
    "cover_image_url": null,
    "footer_expanded": false,
    "funnel": null,
    "header_shows_logo": null,
    "header_shows_name": null,
    "installment_teaser_mode": null,
    "order_summary_mode": null,
    "product_description": 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-02T18:31:00Z",
  "discount": null,
  "has_surcharge": false,
  "is_active": true,
  "label": "Bio Instagram - Atualizado",
  "line_items": [],
  "livemode": true,
  "metadata": {},
  "optional_items": [],
  "payment_method_collection": "always",
  "payment_method_options": null,
  "payment_method_types": null,
  "subscription_data": {},
  "success_url": "https://meusite.com/nova-pagina",
  "template": null,
  "updated_at": "2026-05-02T18:35:00Z",
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

Webhook

Quando a chamada altera algum campo, a Chargefy emite payment.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.

{
  "id": "evt_Df6LzwhaEPuM2Hud",
  "object": "event",
  "created_at": "2026-05-02T18:35:00Z",
  "data": {
    "object": {
      "id": "plink_HTFCXiiJFWgEdqH5",
      "object": "payment_link",
      "allow_discount_codes": false,
      "cancel_url": null,
      "checkout_experience": {
        "banner": null,
        "confirmation_message": null,
        "cover_image_url": null,
        "footer_expanded": false,
        "funnel": null,
        "header_shows_logo": null,
        "header_shows_name": null,
        "installment_teaser_mode": null,
        "order_summary_mode": null,
        "product_description": 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-02T18:31:00Z",
      "discount": null,
      "has_surcharge": false,
      "is_active": true,
      "label": "Bio Instagram - Atualizado",
      "line_items": [],
      "livemode": true,
      "metadata": {},
      "optional_items": [],
      "payment_method_collection": "always",
      "payment_method_options": null,
      "payment_method_types": null,
      "subscription_data": {},
      "success_url": "https://meusite.com/nova-pagina",
      "template": null,
      "updated_at": "2026-05-02T18:35:00Z",
      "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
    },
    "previous_attributes": {
      "label": "Bio Instagram - Plano Pro",
      "metadata": {},
      "payment_method_collection": "always",
      "subscription_data": {},
      "success_url": "https://meusite.com/obrigado"
    }
  },
  "livemode": true,
  "organization": "org_KfWXSeiuME53Ms77",
  "request": {
    "id": "req_yW7w9XbYsfXQmPN2"
  },
  "type": "payment.link.updated"
}

Trocar o preço de um link

cURL

curl -X POST "https://api.chargefy.io/v1/payment-links/plink_HTFCXiiJFWgEdqH5" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_QW2nSe8M5UjR3xKP",
        "quantity": 1
      }
    ]
  }'

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.

Erros comuns

Status	`code`	Quando
`400`	`invalid_request`	`line_items` enviado mas vazio ou inválido.
`400`	`invalid_request`	Itens recorrentes com `interval` ou `interval_count` diferentes no mesmo link.
`400`	`invalid_request`	O estado resultante combina `has_surcharge: true` com item recorrente — em qualquer direção do update.
`400`	`invalid_request`	`allow_discount_codes` enviado com valor que não é booleano.
`403`	`permission_denied`	API key sem acesso à organização dona do link.
`404`	`resource_missing`	`id` não existe na organização atuante.

object | null

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.

integer | null

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.

array | null

Meios oferecidos no checkout: credit_card, pix e boleto. Envie uma lista não vazia, sem repetições. null herda a organização; omitir em uma atualização preserva a escolha. Novas sessões guardam os meios efetivos na criação.

curl -X POST "https://api.chargefy.io/v1/payment-links/plink_HTFCXiiJFWgEdqH5" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Bio Instagram - Atualizado",
    "metadata": {},
    "payment_method_collection": "always",
    "subscription_data": {},
    "success_url": "https://meusite.com/nova-pagina"
  }'

{
  "id": "plink_HTFCXiiJFWgEdqH5",
  "object": "payment_link",
  "allow_discount_codes": false,
  "cancel_url": null,
  "checkout_experience": {
    "banner": null,
    "confirmation_message": null,
    "cover_image_url": null,
    "footer_expanded": false,
    "funnel": null,
    "header_shows_logo": null,
    "header_shows_name": null,
    "installment_teaser_mode": null,
    "order_summary_mode": null,
    "product_description": 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-02T18:31:00Z",
  "discount": null,
  "has_surcharge": false,
  "is_active": true,
  "label": "Bio Instagram - Atualizado",
  "line_items": [],
  "livemode": true,
  "metadata": {},
  "optional_items": [],
  "payment_method_collection": "always",
  "payment_method_options": null,
  "payment_method_types": null,
  "subscription_data": {},
  "success_url": "https://meusite.com/nova-pagina",
  "template": null,
  "updated_at": "2026-05-02T18:35:00Z",
  "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Atualizar um link de pagamento

Autenticação

Parâmetros de caminho

Attributes

Resposta

Webhook

Trocar o preço de um link

Erros comuns

​Autenticação

​Parâmetros de caminho

​Attributes

​Resposta

​Webhook

​Trocar o preço de um link

​Erros comuns

Autenticação

Parâmetros de caminho

Attributes

Resposta

Webhook

Trocar o preço de um link

Erros comuns