Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks de assinatura usam um envelope próprio. O event de topo é sempre subscription; o nome concreto do evento fica em data.event_type.

​
Exemplo de payload entregue

{
  "api_version": "v2",
  "id": "120ebf7cc24835b5ea33ee617bf70cb91c3a4dcd7413afcb05f61c60d1c9de3d",
  "event": "subscription",
  "url": "https://merchant.example/webhooks/pagou",
  "data": {
    "id": "019e5d23-6ec8-73de-9c95-06093c62ba00",
    "cancel_at_period_end": false,
    "created_at": "2026-05-25T03:17:43.753Z",
    "current_period_start": "2026-05-25T03:17:43.752Z",
    "current_period_end": "2026-05-26T03:17:43.752Z",
    "cycle_count": 1,
    "failure_policy": "retry_then_cancel",
    "interval": "day",
    "interval_count": 1,
    "status": "active",
    "trial_end": null,
    "updated_at": "2026-05-25T03:17:46.219Z",
    "event_type": "subscription.created",
    "occurred_at": "2026-05-25T03:17:46.255Z",
    "customer_email": "buyer@example.com",
    "previous_status": null,
    "subscription_cycle": 1,
    "amount": 500,
    "currency": "BRL",
    "latest_transaction": {
      "id": "019e5d23-6ed7-7121-a667-41e5ac929c72",
      "correlation_id": "first_charge_13_1779679063767",
      "method": "credit_card",
      "status": "paid",
      "amount": 500,
      "currency": "BRL",
      "installments": 1,
      "paid_amount": "500",
      "paid_at": "2026-05-25T03:17:46.159Z"
    }
  }
}
Eventos de falha usam os mesmos campos da assinatura e também podem trazer contexto de retentativa, como attempt_number e failure_reason.

​
Eventos emitidos hoje

  • subscription.created
  • subscription.started
  • subscription.renewed
  • subscription.updated
  • subscription.canceled
  • subscription.payment_failed
  • subscription.past_due
  • subscription.trial_will_end
  • subscription.chargeback_received

​
Guia de tratamento

  • Faça deduplicação pelo id do evento no topo.
  • Use data.event_type para rotear a lógica de negócio.
  • Use data.status para o estado atual da assinatura.
  • Use latest_transaction para a transação de cobrança ligada ao evento.
  • Use data.id, não um ID numérico de banco, como identificador público da assinatura.
  • Reconcilie com GET /v2/subscriptions/{id} se a entrega ou o processamento for interrompido.

​
Leia a seguir