> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paynext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Types

> Reference for PayNext v2 webhook event types across payments, refunds, and subscriptions, plus the legacy v1 events and how they map.

PayNext emits a webhook event for each concrete lifecycle transition. Subscribe only to the events your application needs and route on the `type` field—no payload diffing required.

The **v2** taxonomy is granular: one event type means one thing happened. Each v2 event carries `api_version: "2.0.0"`. New endpoints default to v2. See [Versioning](/webhooks/introduction/versioning) for how v1 and v2 run in parallel.

<Note>
  Not every payment emits every event. Sequences vary by flow and processor—auto-capture skips `payment_v2.authorized`, and some methods go straight to `payment_v2.settling` or `payment_v2.settled`.
</Note>

## Payment events

Payments move through the `PENDING`, `INCOMPLETE`, `AUTHORIZED`, `SETTLING`, `SETTLED`, `FAILED`, `DECLINED`, `CANCELLED`, and `BLOCKED` statuses. Each transition emits a dedicated event.

| Event                   | Fires when                                | Notes                                                                                                                                                                          |
| :---------------------- | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_v2.created`    | A payment record is created (`PENDING`)   | Start order tracking                                                                                                                                                           |
| `payment_v2.incomplete` | Moves to `INCOMPLETE`                     | Customer action needed before authorization (<Tooltip tip="3D Secure—authentication protocol that adds verification for online card payments.">3DS</Tooltip> or setup pending) |
| `payment_v2.authorized` | Moves to `AUTHORIZED`                     | Funds held, not yet captured                                                                                                                                                   |
| `payment_v2.settling`   | Moves to `SETTLING`                       | Capture in progress                                                                                                                                                            |
| `payment_v2.settled`    | First transition to `SETTLED`             | The revenue trigger—fires exactly once                                                                                                                                         |
| `payment_v2.failed`     | Moves to `FAILED`                         | Technical or processor failure                                                                                                                                                 |
| `payment_v2.declined`   | Moves to `DECLINED`                       | Carries `status_reason` with the decline details—see the [payment object](/webhooks/objects/payment/payment)                                                                   |
| `payment_v2.cancelled`  | Moves to `CANCELLED`                      | Void or reversal                                                                                                                                                               |
| `payment_v2.blocked`    | Moves to `BLOCKED`                        | Blocked by a [workflow](/guides/platform/workflows)                                                                                                                            |
| `payment_v2.updated`    | Attributes change without a status change | ARN, fraud-alert data, or metadata updates. **Not** a revenue trigger                                                                                                          |

<Warning>
  Payment and subscription events are the source of truth for fulfillment—not the SDK's [`onCheckoutComplete`](/sdk-reference/web-sdk/customization/behavior) callback, which runs in the browser and isn't guaranteed to fire. Grant access and fulfill orders from `payment_v2.settled` (and `subscription_v2.created` for subscriptions), not from the client-side callback.
</Warning>

<Tip>
  Key off `payment_v2.settled` for revenue and fulfillment. It fires once, on the first transition to `SETTLED`—later attribute changes arrive as `payment_v2.updated` and never re-trigger revenue.
</Tip>

<Note>
  Fraud-alert data (Visa RDR, Order Insight, Compelling Evidence) and dispute details flow through `payment_v2.updated` on the embedded objects—there is no dedicated fraud or dispute event.
</Note>

## Refund events

A refund rides on the payment object, so refund events belong to the **`payment_v2`** group and carry the payment with an embedded `refund` field. Correlate by `payment_id`. Refunds move through `PENDING`, `SETTLING`, `SETTLED`, `DECLINED`, and `FAILED`.

| Event                        | Fires when                   | Notes                                       |
| :--------------------------- | :--------------------------- | :------------------------------------------ |
| `payment_v2.refund.created`  | Refund initiated (`PENDING`) | Trigger return workflows                    |
| `payment_v2.refund.settling` | Moves to `SETTLING`          | Optional, parity with `payment_v2.settling` |
| `payment_v2.refund.settled`  | Moves to `SETTLED`           | Money returned to the customer              |
| `payment_v2.refund.declined` | Moves to `DECLINED`          | Refund rejected by the processor            |
| `payment_v2.refund.failed`   | Moves to `FAILED`            | Technical or processor failure              |

<Note>
  A payment can have more than one refund (partial refunds). Refund details are embedded on the payment object; correlate events by `payment_id` and the refund's `processor_transaction_id`. A payment reaching `REFUNDED` status is surfaced through these `payment_v2.refund.*` events—there is no `payment_v2.refunded` payment event.
</Note>

## Subscription events

Subscription events map to lifecycle transitions. The `status` field (`trial`, `active`, `past_due`, `scheduled_for_cancellation`, `cancelled`) tells you the resulting state.

| Event                                        | Fires when                                      | Notes                                                                              |
| :------------------------------------------- | :---------------------------------------------- | :--------------------------------------------------------------------------------- |
| `subscription_v2.created`                    | A subscription is created                       | `status` shows `trial` vs `active`                                                 |
| `subscription_v2.activated`                  | Becomes active from a non-active state          | Trial → paid conversion, or reactivation from a cancelled subscription             |
| `subscription_v2.renewed`                    | Recurring renewal, or `past_due` recovery       | An already-active or past-due subscription renews                                  |
| `subscription_v2.past_due`                   | A renewal fails and dunning begins              | Re-emitted on each retry, carrying `past_due.attempt_count`                        |
| `subscription_v2.scheduled_for_cancellation` | Cancellation scheduled for period end           | Customer keeps access until the cycle ends                                         |
| `subscription_v2.cancelled`                  | Subscription ends                               | Fires for both voluntary and dunning-exhausted cancellation                        |
| `subscription_v2.updated`                    | Plan or metadata change without a status change | Also fires when a scheduled cancellation is reversed (un-cancel before period end) |

<Tip>
  To distinguish state changes that share a status: **trial → paid** and **reactivation** emit `subscription_v2.activated`; a **recurring renewal or past-due recovery** emits `subscription_v2.renewed`; an **un-cancel** (scheduled → active) emits `subscription_v2.updated`.
</Tip>

### Dunning and retries

When a renewal payment fails, the subscription enters `past_due` and PayNext retries automatically. Each retry emits one `subscription_v2.past_due` event carrying an incremented `past_due.attempt_count`, so you can tell attempts apart. If all retries fail, the subscription transitions to `cancelled`.

```json theme={"system"}
{
  "past_due": {
    "attempt_count": 3,
    "max_attempts_count": 8
  }
}
```

## Payment method events

A saved payment method keeps the same ID for its whole life, but its details change underneath that ID—a reissued card brings a new number and expiry, and a network token is refreshed, suspended, or removed by the card network. This event is the only signal that those details moved.

| Event                             | Fires when                      | Notes                                                                                                                  |
| :-------------------------------- | :------------------------------ | :--------------------------------------------------------------------------------------------------------------------- |
| `customer.payment_method.updated` | A stored payment method changes | Carries the full [customer object](/webhooks/objects/customer/customer) with every payment method in its current state |

It fires once per applied change—a lifecycle `status` change, a card reissue, refreshed card details, or a removed network token. Duplicate and out-of-order notifications from the card network don't produce an event.

<Warning>
  If you cache card details such as `last4`, the expiry, or the brand against a payment method ID, refresh your copy when this event arrives. The ID stays the same after a reissue, so nothing else tells you the card behind it changed.
</Warning>

<Tip>
  A card whose `status` is `expired` can still be chargeable while its network token is `active`. Read the two together before prompting a customer for a new card—see [Payment methods](/guides/platform/payment-methods).
</Tip>

## Legacy (v1) events

<Warning>
  The v1 event types are **deprecated**. They keep working for existing endpoints, but new integrations should use v2. See [Versioning](/webhooks/introduction/versioning).
</Warning>

v1 uses coarse events: `payment.updated` and `subscription.updated` fire on every state change, so consumers must diff the payload to learn what happened. Map them to v2 as follows.

| v1 event                 | v2 equivalents                                                                                                                                                                                                |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `payment.created`        | `payment_v2.created`                                                                                                                                                                                          |
| `payment.updated`        | `payment_v2.incomplete`, `payment_v2.authorized`, `payment_v2.settling`, `payment_v2.settled`, `payment_v2.failed`, `payment_v2.declined`, `payment_v2.cancelled`, `payment_v2.blocked`, `payment_v2.updated` |
| `refund.created`         | `payment_v2.refund.created`                                                                                                                                                                                   |
| `refund.updated`         | `payment_v2.refund.settling`, `payment_v2.refund.settled`, `payment_v2.refund.declined`, `payment_v2.refund.failed`                                                                                           |
| `subscription.created`   | `subscription_v2.created`                                                                                                                                                                                     |
| `subscription.updated`   | `subscription_v2.created`,¹ `subscription_v2.activated`, `subscription_v2.renewed`, `subscription_v2.past_due`, `subscription_v2.scheduled_for_cancellation`, `subscription_v2.updated`                       |
| `subscription.cancelled` | `subscription_v2.cancelled`                                                                                                                                                                                   |

¹ v2 deliberately corrects v1 here: the initial activation of a no-trial subscription (previous status none) emits `subscription.updated` under v1 but `subscription_v2.created` under v2. During the overlap the same transition goes out under both names—this is intended, not a duplicate.

## Classifying events for analytics

Some distinctions aren't signalled as separate event types. Derive them from the payload:

| To distinguish                 | Use                                                                                                                                                                                  |
| :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Voluntary vs involuntary churn | The `cancellation_details.reason` on the [subscription object](/webhooks/objects/subscription/subscription), or a `subscription_v2.cancelled` preceded by `subscription_v2.past_due` |
| Initial vs recurring charge    | `payment_type` (`CIT` = customer-initiated, often initial; `MIT` = merchant-initiated, rebills) plus `subscription_id`                                                               |
| Chargebacks and disputes       | The embedded dispute data on `payment_v2.updated`—there is no dedicated dispute event                                                                                                |

See the [payment object](/webhooks/objects/payment/payment) and [subscription object](/webhooks/objects/subscription/subscription) for full payload schemas.