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.

Subscription webhooks use a dedicated envelope. The top-level event is always subscription; the concrete event name is in data.event_type.

​
Example delivery payload

{
  "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"
    }
  }
}
Failure events include the same subscription fields plus retry context such as attempt_number and failure_reason.

​
Events emitted today

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

​
Handling guidance

  • Deduplicate by the top-level event id.
  • Use data.event_type to route business logic.
  • Use data.status for the current subscription state.
  • Use latest_transaction for the billing transaction linked to the event.
  • Use data.id, not a numeric database id, as the public subscription identifier.
  • Reconcile with GET /v2/subscriptions/{id} if delivery or processing is interrupted.