Assinaturas

Eventos Webhook

Webhooks são enviados para URLs cadastradas via POST /v1/users/webhooks ou pelo painel em Integração → Webhooks (botão + Webhook). O seller escolhe quais eventos receber; o sistema só entrega eventos presentes na lista events do webhook ativo.

← Voltar à Referência

Configuração

Via API, cadastre a URL e a lista de eventos desejados. No painel, use Integração → Webhooks e o botão + Webhook:

{
  "url": "https://sua-app.com/webhooks/validapay",
  "events": [
    "subscription.created",
    "subscription.activated",
    "subscription.renewed",
    "subscription.canceled",
    "subscription.cancel_scheduled",
    "subscription.upgraded",
    "subscription.item_added",
    "subscription.item_removed",
    "subscription.downgrade_scheduled",
    "subscription.trial",
    "charge.created",
    "payment.success",
    "payment.failed"
  ]
}

Testar payload: POST /v1/users/webhooks/test com entity = nome do evento.

Entrega e segurança

Método	POST para a URL cadastrada
Content-Type	application/json
Assinatura	X-Webhook-Signature: t={timestamp},v1={hmac_sha256}
Cálculo	HMAC-SHA256(secret, "{timestamp}.{body_json}")
Auth opcional	x-access-token se authToken configurado
Filtro	Apenas webhooks status: active com evento na lista events

O secret retornado na criação deve ser usado para validar a autenticidade do payload.

Sequências típicas

Boleto / PIX — assinatura recorrente

subscription.createdcharge.created(cliente paga)payment.successsubscription.activated— próximo ciclo —charge.createdpayment.successsubscription.renewed

Cartão — 1º pagamento

subscription.createdcharge.createdsubscription.activated(payment.success não dispara)

Trial

subscription.trial(fim do trial)charge.createdpayment.successsubscription.activated

Upgrade (pro-rata)

POST /prorata (sem webhook)PUT /items/:itemIdcharge.createdpayment.success (boleto/PIX) ou imediato (cartão)subscription.upgraded

Downgrade

PUT /items/:itemIdsubscription.downgrade_scheduled

Add item

POST /itemscharge.createdpayment.success (boleto/PIX)subscription.item_added

Remove item

DELETE /items/:itemIdsubscription.item_removed

Cancelamento imediato

DELETE /v1/subscriptions/:idsubscription.canceled

Cancelamento no fim do ciclo

DELETE /v1/subscriptions/:id { atPeriodEnd: true }subscription.cancel_scheduled(fim do ciclo)subscription.canceled (cancelReason: SCHEDULED_AT_PERIOD_END)

Inadimplência

charge.createdpayment.failed (uma vez por tentativa)(dunning esgotado)subscription.canceled

Relação com operações da API

Operação	Webhooks disparados
Criação via checkout/charges	subscription.created → charge.created → (payment.success) → subscription.activated
DELETE /v1/subscriptions/:id	subscription.canceled
DELETE /v1/subscriptions/:id { atPeriodEnd: true }	subscription.cancel_scheduled → (fim do ciclo) subscription.canceled
PUT /items/:itemId (upgrade)	charge.created → payment.success → subscription.upgraded
PUT /items/:itemId (downgrade)	subscription.downgrade_scheduled
POST /items (add item)	charge.created → payment.success → subscription.item_added
DELETE /items/:itemId (remove item)	subscription.item_removed
POST /prorata	Nenhum (apenas simulação)
Renovação automática	charge.created → payment.success → subscription.renewed

Detalhamento por evento

subscription.created

assinaturastatus típico: PENDING ou AWAITING_PAYMENT

Assinatura recorrente criada, antes do primeiro pagamento confirmado.

Quando: Imediatamente após checkout com itens RECURRING. Não dispara para assinaturas apenas ONE_TIME.

currentCycle é null
Não dispara subscription.created no fluxo trial — apenas subscription.trial

Exemplo de payload

{
  "event": "subscription.created",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "PENDING",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": null,
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.trial

assinaturastatus típico: TRIALING

Período de trial iniciado para um preço com trialDays.

Quando: Checkout com preço que possui período de trial.

currentCycleNumber: 0
currentCycle é null
Não existe objeto trial no payload — a duração está em items[].price.trialDays

Exemplo de payload

{
  "event": "subscription.trial",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "TRIALING",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 0,
  "metadata": {},
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "TRIALING",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": 7
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": null,
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.activated

assinaturastatus típico: ACTIVE

Primeiro pagamento confirmado — assinatura ativa.

Quando: Ciclo 1 pago por confirmação assíncrona (boleto/PIX), checkout cartão (síncrono) ou pagamento manual de invoice.

Sequência típica (boleto/PIX): subscription.created → charge.created → payment.success → subscription.activated
No checkout com cartão, payment.success não dispara — use subscription.activated como confirmação do 1º pagamento

Exemplo de payload

{
  "event": "subscription.activated",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.renewed

assinaturastatus típico: ACTIVE

Renovação confirmada (ciclo 2 ou superior).

Quando: Pagamento confirmado do ciclo 2+ pelo motor de ciclos ou por confirmação assíncrona.

Campos exclusivos

Campo	Descrição
`nextCycleChargeDate`	Data de cobrança do próximo ciclo
`nextCycleAmount`	Valor previsto do próximo ciclo

Geralmente acompanhado de charge.created e payment.success
nextCycleChargeDate e nextCycleAmount vêm quando o evento é emitido pelo motor de cobrança

Exemplo de payload

{
  "event": "subscription.renewed",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "nextCycleChargeDate": "2026-09-10T14:45:05.953Z",
  "nextCycleAmount": 99.99
}

subscription.canceled

assinaturastatus típico: CANCELED

Assinatura cancelada via API ou motor de recorrência (dunning).

Quando: DELETE /v1/subscriptions/:id ou cancelamento por inadimplência.

Campos exclusivos

Campo	Descrição
`cancelReason`	Motivo informado ou gerado pelo sistema

currentCycle continua preenchido, com o status em que o ciclo ficou (CANCELED ou PAID)
Cancelamento agendado que venceu chega com cancelReason: "SCHEDULED_AT_PERIOD_END"
Internamente boleto/PIX pode usar subscription.canceled.boleto_pix, mas o seller sempre recebe subscription.canceled

Exemplo de payload

{
  "event": "subscription.canceled",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "CANCELED",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": "2026-07-03T18:25:09.025Z",
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "CANCELED",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": null,
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "cancelReason": "Cancelado pelo cliente"
}

subscription.cancel_scheduled

assinaturastatus típico: ACTIVE (inalterado)

Cancelamento agendado para o fim do período vigente — a assinatura continua ativa até lá.

Quando: DELETE /v1/subscriptions/:id com body { "atPeriodEnd": true }, ou PATCH com { "action": "cancel", "atPeriodEnd": true }.

Campos exclusivos

Campo	Descrição
`cancelAtPeriodEnd`	Sempre true neste evento
`cancelRequestedAt`	Momento em que o cancelamento foi solicitado
`effectiveAt`	Data em que o cancelamento entra em vigor (nextCycleChargeDate); null se não houver próximo ciclo
`cancelReason`	Motivo informado na solicitação

A assinatura permanece ACTIVE e o ciclo vigente segue válido até effectiveAt
Não interrompa o acesso do cliente ao receber este evento — aguarde subscription.canceled
O parâmetro de entrada é atPeriodEnd (booleano true); cancelAtPeriodEnd é o campo devolvido no payload
Sem atPeriodEnd o DELETE cancela imediatamente e dispara subscription.canceled
Reverter o agendamento: PATCH com { "action": "revoke_scheduled_cancel" } — nesse caso nenhum subscription.canceled é disparado

Exemplo de payload

Ao chegar effectiveAt, um subscription.canceled é disparado com status CANCELED.

{
  "event": "subscription.cancel_scheduled",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "metadata": {},
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "cancelAtPeriodEnd": true,
  "cancelRequestedAt": "2026-07-03T18:25:09.025Z",
  "effectiveAt": "2026-08-03T18:25:09.025Z",
  "cancelReason": "Cancelado pelo cliente",
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.upgraded

assinaturastatus típico: ACTIVE

Upgrade de plano confirmado após pagamento do pro-rata.

Quando: Após PUT /items/:itemId com valor maior e confirmação de pagamento.

Disparado após applyUpgrade() — items e valores refletem o novo plano

Exemplo de payload

Base igual a subscription.activated; em produção items e valores refletem o upgrade.

{
  "event": "subscription.upgraded",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.item_added

assinaturastatus típico: ACTIVE

Item recorrente ou ONE_TIME adicionado e cobrança confirmada.

Quando: Após POST /items e confirmação via applyAddItem() ou applyOneTimeItem().

Acompanhado de charge.created + payment.success (boleto/PIX)

Exemplo de payload

{
  "event": "subscription.item_added",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.item_removed

assinaturastatus típico: ACTIVE

Item removido da assinatura.

Quando: DELETE /items/:itemId. O novo valor passa a valer no próximo ciclo, salvo remoção aplicada ao ciclo corrente.

Só assinável via POST /v1/users/webhooks — o painel ainda não lista este evento

Exemplo de payload

Base igual a subscription.activated; em produção items reflete a assinatura já sem o item.

{
  "event": "subscription.item_removed",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.downgrade_scheduled

assinaturastatus típico: ACTIVE

Downgrade agendado para o próximo ciclo, sem cobrança imediata.

Quando: PUT /items/:itemId com valor menor ou quantidade reduzida.

Efetivo em nextCycleChargeDate
Item pode conter scheduledChange no payload enriquecido

Exemplo de payload

{
  "event": "subscription.downgrade_scheduled",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

charge.created

cobrançastatus típico: status da COBRANÇA (PENDING, PROCESSING…), não da assinatura

Qualquer cobrança criada vinculada à assinatura.

Quando: 1º ciclo, renovação, pro-rata de upgrade, add item, item ONE_TIME ou cobrança avulsa.

Campos exclusivos

Campo	Descrição
`chargeId`	ID da cobrança
`invoiceId`	ID da fatura, quando houver
`transactionId`	ID da transação
`amount / currency`	Valor em reais (BRL)
`paymentType`	CREDIT_CARD, BOLETO, PIX ou PIX_AUTOMATICO
`type`	RECURRING, PRORATA_UPGRADE, PRORATA_ADD_ITEM, ONE_TIME_ITEM, etc.
`emvQrCode`	Copia-e-cola do Pix, quando paymentType é PIX
`pixCollectionType`	COB ou COBV
`dueDate`	Vencimento da cobrança
`recurrencyId`	Recorrência do Pix Automático, quando houver

Atenção: status neste evento é o da cobrança recém-criada — filtrar por status === "ACTIVE" não retorna nada
Cobranças avulsas chegam com interval: "ONE_TIME" e itens sem os blocos price e product

Exemplo de payload

{
  "event": "charge.created",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "PENDING",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": null,
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "chargeId": "cha_1770730676238_example",
  "invoiceId": "inv_1770730676238_example",
  "transactionId": "3080767385",
  "amount": 99.99,
  "currency": "BRL",
  "paymentType": "PIX",
  "type": "RECURRING",
  "pixCollectionType": "COBV",
  "emvQrCode": "00020101021226960014br.gov.bcb.pix…",
  "dueDate": "2026-08-03T00:00:00Z"
}

payment.success

pagamentostatus típico: ACTIVE

Pagamento confirmado de forma assíncrona (boleto/PIX) ou item ONE_TIME pago.

Quando: Confirmação de pagamento assíncrono. Não dispara no checkout com cartão.

Para cartão no 1º pagamento ou pro-rata, use subscription.activated ou subscription.upgraded

Exemplo de payload

{
  "event": "payment.success",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

payment.failed

pagamentostatus típico: não se aplica — schema próprio, sem a base de assinatura

Falha de pagamento em cobrança recorrente (ex.: antifraude).

Quando: Cobrança recorrente recusada, uma vez por tentativa do motor de retentativa.

Campos exclusivos

Campo	Descrição
`accountId`	Conta do seller — este evento usa accountId, não accountNumber
`failed`	Mensagem de erro do pagamento, em texto livre
`name / email / taxId`	Dados do pagador
`customerId / cellphone / item`	Frequentemente null

Único evento de pagamento que não carrega subscriptionId, items nem currentCycle
failed é uma string, não um objeto

Exemplo de payload

{
  "event": "payment.failed",
  "timestamp": "2026-06-20T00:09:17.334Z",
  "accountId": "4231833",
  "customerId": null,
  "name": "João da Silva",
  "email": "joao@example.com",
  "taxId": "11144477735",
  "cellphone": null,
  "item": null,
  "metadata": null,
  "failed": "Pagamento não autorizado"
}

Observações importantes

Quando o evento possui subscriptionId, o payload é enriquecido com dados vivos (items, customer, currentCycle). Se o enrichment falhar, um payload simplificado é enviado.
Campos adicionais por evento: cancelReason em subscription.canceled; failed em payment.failed; trial em subscription.trial.
Cadastre webhooks via POST /v1/users/webhooks ou no painel em Integração → Webhooks (botão + Webhook).
Valores monetários nos payloads são sempre em reais (BRL), nunca em centavos.