Evento payment.link.created

Evento `payment.link.created`

Disparado quando um payment link é criado via POST /v1/payment-links. Use este evento para registrar que uma URL reutilizável de checkout foi criada e já pode aceitar novos cliques enquanto is_active for true. Cada clique no link materializa uma nova checkout.session com as regras configuradas no payment link. data.object carrega o payment_link completo, no mesmo contrato público do recurso — o mesmo shape retornado por create, get e update. Use id, is_active e metadata para identificar o link e correlacionar com o seu sistema.

Um payment link não é uma cobrança nem uma invoice. Ele é uma configuração reutilizável de checkout; as tentativas de pagamento aparecem depois nos eventos de checkout.session.*, payment.intent.* e charge.*.

Quando acontece

Situação	Como aparece no payload
Link criado com sucesso	`data.object.object: "payment_link"` e `data.object.is_active: true`.
Link criado com metadata	`metadata` ecoa o objeto enviado na criação.
Link criado em modo produção	`livemode: true` no envelope do evento.
Link criado por organização conectada	`organization` identifica a organização que originou o evento.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (plink_*) como chave do payment link no seu sistema.
Marque o link como disponível para novos cliques quando is_active for true.
Use metadata para correlacionar o link com campanhas, produtos ou referências internas.
Use organization no envelope para rotear o evento quando você opera várias organizações.
Não trate este evento como pagamento concluído; acompanhe a finalização pelos eventos da sessão e da cobrança.

Campos importantes

Campo	O que observar
`data.object.id`	ID do payment link criado.
`data.object.is_active`	Indica se o link aceita novos cliques.
`metadata`	Ecoa os metadados enviados na criação.
`created_at`	Momento em que o link foi criado.
`updated_at`	Vem `null` enquanto o link nunca foi atualizado.
`organization`	Organização que originou o evento.

Variações de catálogo

Variação	O que muda
Link com preço do catálogo	O link nasce a partir de um `price` existente e o evento continua sendo `payment.link.created`.
Link com produto do catálogo e preço ad-hoc	O produto vem do catálogo, mas o valor é específico daquele link.
Link totalmente ad-hoc	Produto e preço são definidos para o link sem exigir cadastro prévio no catálogo.

Exemplo de payload

{
  "id": "evt_7ESPB1guyufESspk",
  "object": "event",
  "created_at": "2026-05-16T14:09:27Z",
  "data": {
    "object": {
      "id": "plink_dwtV2AAL16Cu8f2N",
      "object": "payment_link",
      "allow_discount_codes": false,
      "cancel_url": null,
      "created_at": "2026-05-16T14:09:27Z",
      "discount": null,
      "has_surcharge": false,
      "is_active": true,
      "label": "Plano Pro",
      "line_items": [
        {
          "id": "pli_8Mhhzgag6C1RqK5B",
          "adjustable_quantity": {
            "enabled": false,
            "maximum": null,
            "minimum": null
          },
          "amount_discount": 0,
          "amount_subtotal": 19990,
          "amount_tax": 0,
          "amount_total": 19990,
          "currency": "brl",
          "description": "Plano Pro",
          "metadata": {},
          "position": 0,
          "price": "price_3zqsyLwAPKTQ9a6P",
          "price_data": null,
          "product": "prod_KqhqCWKktQbv6DeT",
          "quantity": 1,
          "recurring_interval": "month",
          "recurring_interval_count": 1,
          "unit_amount": 19990
        }
      ],
      "livemode": true,
      "metadata": {},
      "payment_method_collection": "always",
      "subscription_data": {},
      "success_url": "https://meusite.com/sucesso",
      "updated_at": null,
      "url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
    }
  },
  "livemode": true,
  "organization": "org_PBwio8fp2TquwZGt",
  "request": {
    "id": null
  },
  "type": "payment.link.created"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento payment.link.created