Skip to main content
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 for how v1 and v2 run in parallel.
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.

​
Payment events

Payments move through the PENDING, INCOMPLETE, AUTHORIZED, SETTLING, SETTLED, FAILED, DECLINED, CANCELLED, and BLOCKED statuses. Each transition emits a dedicated event.
Payment and subscription events are the source of truth for fulfillment—not the SDK’s onCheckoutComplete 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.
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.
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.

​
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.
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.

​
Subscription events

Subscription events map to lifecycle transitions. The status field (trial, active, past_due, scheduled_for_cancellation, cancelled) tells you the resulting state.
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.

​
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.

​
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. 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.
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.
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.

​
Legacy (v1) events

The v1 event types are deprecated. They keep working for existing endpoints, but new integrations should use v2. See Versioning.
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. ¹ 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: See the payment object and subscription object for full payload schemas.