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

# Event types

# Webhook Event Types

fype supports a variety of events to keep your system in sync with the payment lifecycle.

## Payment Events

| Event Type           | Description                                                                        |
| :------------------- | :--------------------------------------------------------------------------------- |
| `payment.succeeded`  | Triggered when a payment has been successfully captured by the gateway.            |
| `payment.failed`     | Triggered when a payment attempt fails (e.g., insufficient funds, card declined).  |
| `payment.processing` | Triggered when a payment is in a pending state (e.g., awaiting bank confirmation). |
| `payment.captured`   | Alias for `payment.succeeded` in some provider contexts.                           |

## Refund Events

| Event Type         | Description                                                             |
| :----------------- | :---------------------------------------------------------------------- |
| `refund.processed` | Triggered when a refund has been successfully processed by the gateway. |
| `refund.failed`    | Triggered if a refund attempt fails.                                    |

## Subscription Events

| Event Type                    | Description                                                                     |
| :---------------------------- | :------------------------------------------------------------------------------ |
| `subscription.authenticated`  | Triggered when a recurring mandate is successfully authorized by the customer.  |
| `subscription.activated`      | Triggered when a subscription is fully activated and billing cycles start.      |
| `subscription.charged`        | Triggered when a recurring cycle payment is successfully charged.               |
| `subscription.payment_failed` | Triggered when a recurring cycle payment or authorization attempt fails.        |
| `subscription.paused`         | Triggered when subscription billing is paused.                                  |
| `subscription.resumed`        | Triggered when subscription billing resumes.                                    |
| `subscription.cancelled`      | Triggered when a subscription is permanently cancelled.                         |
| `subscription.completed`      | Triggered when a subscription reaches its billing limits or scheduled end.      |
| `subscription.halted`         | Triggered when billing retries are exhausted (max payment failure retries met). |

## Invoice Events

| Event Type               | Description                                                        |
| :----------------------- | :----------------------------------------------------------------- |
| `invoice.paid`           | Triggered when a subscription cycle invoice is successfully paid.  |
| `invoice.payment_failed` | Triggered when a subscription cycle invoice payment attempt fails. |

## Event Payload Details

Every event contains a `data.object` which represents the normalized entity (Payment, Refund, Subscription, or Invoice).

### Payment Object

```json theme={null}
{
 "id": "uuid",
 "amount": 50000,
 "currency": "INR",
 "status": "succeeded",
 "reference_id": "your_order_id",
 "metadata": {},
 "created_at": "iso_timestamp"
}
```

### Refund Object

```json theme={null}
{
 "id": "uuid",
 "payment_id": "uuid",
 "amount": 25000,
 "status": "processed",
 "created_at": "iso_timestamp"
}
```

### Subscription Object

```json theme={null}
{
 "id": "uuid",
 "customer_id": "uuid",
 "plan_id": "uuid",
 "price_id": "uuid",
 "status": "active",
 "quantity": 1,
 "current_period_start": "iso_timestamp",
 "current_period_end": "iso_timestamp",
 "trial_start": null,
 "trial_end": null,
 "cancel_at_period_end": false,
 "cancelled_at": null,
 "cancellation_reason": null,
 "provider": "razorpay",
 "provider_subscription_id": "sub_12345",
 "metadata_json": {},
 "created_at": "iso_timestamp"
}
```

### Invoice Object

```json theme={null}
{
 "id": "uuid",
 "merchant_id": "uuid",
 "customer_id": "uuid",
 "subscription_id": "uuid",
 "invoice_number": "INV-2026-0001",
 "status": "paid",
 "currency": "INR",
 "subtotal": 99900,
 "tax_amount": 17982,
 "discount_amount": 0,
 "total": 117882,
 "amount_paid": 117882,
 "amount_due": 0,
 "tax_details": {
 "tax_rate": 18.0,
 "cgst": 8991,
 "sgst": 8991,
 "igst": 0
 },
 "created_at": "iso_timestamp",
 "paid_at": "iso_timestamp"
}
```

## Handling Unsupported Events

Gateways may occasionally send events that are not yet natively mapped by fype. In such cases, fype will still forward the event if possible, prefixed with `unsupported.`. We recommend logging these events but not basing critical business logic on them without verification.