> ## Documentation Index
> Fetch the complete documentation index at: https://beta-developers.mizaniyapay.dz/llms.txt
> Use this file to discover all available pages before exploring further.

# payment.fail: Payment Failed or Cancelled Event

> Reference for the payment.fail webhook event, including event data fields, payload example, and handler implementations in JavaScript and Python.

The `payment.fail` event is sent when a payment fails or is cancelled. Use this event to update the order status in your system and release any held resources.

## Event Data

<ResponseField name="event" type="string" required>
  Always `payment.fail`.
</ResponseField>

<ResponseField name="data.reference" type="string" required>
  The payment reference from your system.
</ResponseField>

<ResponseField name="data.paymentId" type="string" required>
  The unique VTPE payment identifier.
</ResponseField>

## Payload Example

```json theme={null}
{
  "event": "payment.fail",
  "data": {
    "reference": "ORD-2024-001",
    "paymentId": "pay_abc123xyz"
  }
}
```

## Handling This Event

<CodeGroup>
  ```javascript Node.js theme={null}
  if (event === "payment.fail") {
    await db.cancelOrder({
      reference: data.reference,
      paymentId: data.paymentId
    });
    // Optionally notify the customer
  }
  ```

  ```python Python theme={null}
  if event == "payment.fail":
      db.cancel_order(
          reference=data["reference"],
          payment_id=data["paymentId"]
      )
      # Optionally notify the customer
  ```
</CodeGroup>

<Tip>
  Use the `reference` field to look up the associated order in your database and release any reservations or inventory holds tied to that order.
</Tip>