Catálogo de eventos de webhook do Therius e suas cargas

Esta página lista cada tipo de evento que o Therius entrega a um endpoint de webhook configurado. Assine um subconjunto em Desenvolvedores → Webhooks, ou deixe a seleção vazia para recebê-los todos. Veja Visão geral de webhooks para os detalhes de entrega, nova tentativa e verificação de assinatura.

Eventos de pagamento

As cargas de eventos de pagamento usam este envelope:

{
  "event": "payment.captured",
  "environment": "production",
  "created_at": "2026-08-29T12:00:00Z",
  "data": {
    "payment_id": "b1f2...",
    "transaction_id": "t_9a8b...",
    "order_code": "ORDER-001",
    "payment_code": "PAY-abc123",
    "merchant_id": 42,
    "status": "captured",
    "amount": 1999,
    "currency": "USD",
    "exponent": 2,
    "authorization_code": "OK123"
  }
}

Quando o pagamento salvou um cartão (tokenize: true), data.token o traz como { "id": "vt_...", "expirationDate": "...", "tokenCreationReference": "..." }, o mesmo objeto da resposta do purchase. Um cartão em um pagamento assíncrono (o provedor respondeu pending) é salvo quando o pagamento é resolvido. Se isso acontecer depois de o webhook ser enviado, data.token não vem e você recebe um evento token.created.

Evento	Dispara quando
`payment.authorized`	Fundos foram reservados por uma chamada de `authorization` (ou o trecho de autorização de um `purchase`).
`payment.captured`	Uma captura teve sucesso — incluindo a captura automática dentro de `purchase`, e a confirmação de um pagamento APM ou de voucher assíncrono.
`payment.refused`	O emissor ou o adquirente recusou o pagamento. Corresponde a um status `declined` na resposta síncrona da API — veja Pagamentos recusados para saber como ler a recusa.
`payment.refunded`	Um reembolso foi processado. Dispara a cada reembolso; `data.status` é `refunded` somente depois que o pagamento é totalmente reembolsado.
`payment.canceled`	Uma autorização foi anulada antes da captura.
`payment.chargeback`	Uma disputa foi aberta contra um pagamento liquidado (recebida da notificação de disputa do adquirente).
`payment.capture_failed`	Uma tentativa de captura falhou. O pagamento continua em `authorized`.
`payment.refund_failed`	Uma tentativa de reembolso falhou. O pagamento continua em `captured`.
`payment.cancel_failed`	Uma tentativa de cancelamento falhou. O pagamento continua em `authorized`.

Os nomes dos eventos de webhook usam refused onde o campo status da resposta síncrona da API usa declined, e payment.<status> para estados terminais como expired. Corresponda à string event, não a uma análise de substring.

Eventos de assinatura

As cargas de eventos de assinatura usam um envelope ligeiramente diferente — subscription_id é um campo de nível superior e data carrega o detalhe específico do evento:

{
  "event": "subscription.renewed",
  "created_at": "2026-08-29T12:00:00Z",
  "subscription_id": "sub_abc123",
  "merchant_id": 42,
  "data": {
    "...": "event-specific fields (invoice, period dates, amount, failure reason, ...)"
  }
}

Evento	Dispara quando
`subscription.created`	Uma assinatura foi criada.
`subscription.trial_ended`	Um período de teste gratuito terminou e o faturamento começa.
`subscription.renewed`	Uma renovação programada foi cobrada com sucesso.
`subscription.payment_failed`	Uma cobrança de renovação falhou.
`subscription.dunning_started`	A assinatura entrou em `past_due` e a sequência de novas tentativas de gestão de cobranças começou.
`subscription.suspended`	Todas as novas tentativas de gestão de cobranças se esgotaram; a assinatura está inativa até o método de pagamento ser atualizado.
`subscription.reactivated`	Uma assinatura `suspended` foi recuperada (novo método de pagamento ou nova tentativa bem-sucedida).
`subscription.paused`	A assinatura foi pausada manualmente.
`subscription.resumed`	Uma assinatura pausada foi retomada.
`subscription.canceled`	A assinatura foi cancelada de forma permanente.
`subscription.completed`	A assinatura atingiu seu número fixo de ciclos de faturamento e terminou naturalmente.
`subscription.payment_method_updated`	O cartão armazenado na assinatura foi substituído.
`subscription.payment_method_removed`	O cliente excluiu o cartão salvo em que a assinatura renova. A assinatura continua cobrando esse cartão até que você substitua a forma de pagamento dela. `data.token` é o token.
`subscription.plan_change_scheduled`	Uma mudança de plano foi enfileirada para ser aplicada na próxima data de faturamento.
`subscription.plan_changed`	Uma mudança de plano entrou em vigor.

Eventos de cartões salvos

Os eventos de cartões salvos avisam quando um token é criado para um pagamento assíncrono e quando um token que você armazenou deixa de poder ser usado. Veja o ciclo de vida do token para as regras de retenção.

{
  "event": "token.deleted",
  "environment": "production",
  "created_at": "2026-03-02T14:15:00Z",
  "merchant_id": 42,
  "data": {
    "token": "vt_4xK9mNpQ2rLsT7uV",
    "status": "deleted",
    "reason": "unused",
    "retentionDays": 30
  }
}

Evento	Dispara quando
`token.created`	Um cartão retido até um pagamento assíncrono ser resolvido foi salvo. `data.token` é o id do token (uma string, como em `token.deleted`), com `data.payment_id`, `data.payment_code`, `data.expirationDate` e `data.tokenCreationReference`. Se o mesmo cartão já estava salvo, `data.token` é o token existente.
`token.deleted`	O cliente ou um agente de suporte excluiu um cartão, um salvamento mais recente do mesmo cartão o substituiu, ou o Therius o retirou. `data.reason` é `deleted`, `expired` ou `unused`. O token continua cobrando até `token.erased`; `data.retentionDays` é o período de retenção que se aplica.
`token.erased`	Os dados do cartão por trás do token foram apagados permanentemente. O token não pode mais ser cobrado.

Eventos de link de pagamento

Um link de pagamento envia seus próprios eventos além dos eventos de pagamento acima. Um pagamento feito em um link continua enviando seus eventos payment.* habituais; os eventos payment_link.* descrevem o que aconteceu com o próprio link. Use data.payment_link_id para identificar o link, e data.payment_id ou data.order_code para identificar o pagamento. Os eventos de link de pagamento usam o mesmo envelope dos eventos de pagamento:

{
  "event": "payment_link.paid",
  "environment": "production",
  "created_at": "2026-10-15T12:00:00Z",
  "data": {
    "payment_link_id": "5b1f0a52-3c0e-4a52-9d57-0c1d7e9f2a10",
    "type": "one-time",
    "title": "Invoice 1042",
    "reference": "INV-1042",
    "merchant_id": 42,
    "status": "used",
    "uses_count": 1,
    "payment_id": "b1f2...",
    "order_code": "INV-1042",
    "payment_status": "captured",
    "amount": 1100,
    "currency": "USD",
    "exponent": 2
  }
}

Evento	Enviado quando
`payment_link.paid`	Um pagamento no link foi aprovado e contado como um uso. `data.status` é `used` quando o link não pode mais receber pagamentos (um link de uso único, ou um link reutilizável que atingiu seu `maxUses`); caso contrário, `active`. Em um link de assinatura, `data.subscription_id` é a nova assinatura.
`payment_link.attempt_failed`	Uma tentativa de pagamento no link foi recusada ou terminou em erro. O link continua `active`, então o pagador pode tentar novamente.
`payment_link.expired`	O link passou da data de expiração sem ser pago. Enviado uma única vez, logo após o horário de expiração.
`payment_link.canceled`	O link foi cancelado, pela API ou pelo dashboard.

Campo	Descrição
`data.payment_link_id`	O ID do link.
`data.type`	`one-time` ou `subscription`.
`data.title`, `data.reference`	O título e a sua referência, como definidos ao criar o link. `null` quando não definidos.
`data.merchant_id`, `data.uses_count`	O lojista, e quantos pagamentos bem-sucedidos o link recebeu até agora.
`data.status`	O status do link após o evento: `used`, `expired` ou `canceled` (`active` em um link reutilizável que ainda pode receber pagamentos). Não é enviado com `payment_link.attempt_failed`.
`data.payment_id`, `data.order_code`, `data.payment_status`, `data.amount`, `data.currency`, `data.exponent`	O pagamento por trás do evento. Enviados com `payment_link.paid` e `payment_link.attempt_failed`. `amount` está em unidades menores.
`data.subscription_id`	Enviado com `payment_link.paid` em um link de assinatura.
`data.expires_at`	Enviado com `payment_link.expired`.
`data.canceled_by`	Enviado com `payment_link.canceled`: `api` ou `dashboard`.

Os eventos de link e os eventos de pagamento do mesmo pagamento são entregas separadas e podem chegar em qualquer ordem. Relacione-os por data.order_code ou data.payment_id, não pela ordem de chegada.

Eventos de teste

Use Desenvolvedores → Webhooks → Enviar evento de teste para entregar uma carga de amostra de qualquer tipo de evento ao seu endpoint sem criar um pagamento ou uma assinatura reais. As entregas de teste aparecem em Entregas recentes ao lado das reais e podem ser reenviadas.

Primeiros passos

Conceitos básicos

Guias

Webhooks

Assistente de IA

Plugins de e-commerce

Catálogo de eventos de webhook do Therius e suas cargas

Eventos de pagamento

Eventos de assinatura

Eventos de cartões salvos

Eventos de link de pagamento

Eventos de teste

​Eventos de pagamento

​Eventos de assinatura

​Eventos de cartões salvos

​Eventos de link de pagamento

​Eventos de teste

Eventos de pagamento

Eventos de assinatura

Eventos de cartões salvos

Eventos de link de pagamento

Eventos de teste