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

# VTPE Payment Lifecycle and State Transitions

> Understand the three VTPE payment events: initialized, success, and fail. Learn what data each event carries and the recommended actions for your system.

VTPE notifies your system about payment state changes through webhook events. Understanding these states helps you build a robust integration that handles payment sessions, confirmations, and failures correctly. This page describes each event, its data fields, and the actions you should take.

## Payment States

A VTPE payment follows a simple state model:

```text theme={null}
initialized -> success
          -> fail
```

After a payment is initialized, it will resolve into either a success or fail state. Each transition triggers a webhook event delivered to your Webhook URL.

## Event Summary

| Event                 | Triggered When                                  | Key Data Fields                                                     |
| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------- |
| `payment.initialized` | A payment session is created for a reference    | `reference`, `amount`, `currency`, `paymentId`                      |
| `payment.success`     | The customer successfully completes the payment | `reference`, `paymentId`, `amount`, `currency`, `paidAt`, `channel` |
| `payment.fail`        | The payment fails or is cancelled               | `reference`, `paymentId`                                            |

## Recommended Actions Per Event

### payment.initialized

Create a pending order record in your system. Record the `paymentId` so you can correlate later events. Do NOT fulfill the order yet; the payment has not been confirmed.

### payment.success

Fulfill the order and record the `paymentId` and `channel`. Send a receipt or confirmation to the customer. Update any inventory or booking systems associated with the reference. The `paidAt` timestamp tells you exactly when the payment was confirmed.

### payment.fail

Release any inventory or reservation holds tied to the reference. Update the order status to failed or cancelled. Optionally notify the customer so they can retry or try a different payment method.

## Channel Values

The `payment.success` event includes a `channel` field that indicates which fulfillment channel handled the payment. The possible values are:

| Channel       | Description                                   |
| ------------- | --------------------------------------------- |
| `AGENCY`      | Payment handled through an agency partner     |
| `DELIVERY`    | Payment handled through a delivery partner    |
| `MARKETPLACE` | Payment handled through a marketplace partner |

<Note>
  Use `paymentId` as an idempotency key when processing webhooks. VTPE may retry webhook delivery, so handle duplicate events safely to avoid double fulfillment.
</Note>

## When Webhooks Do Not Arrive

VTPE makes best-effort webhook delivery, but failures can happen. If a webhook for a reference never arrives, use the [Payment Status API](/api-reference/payments/payment-status) to query the current state directly:

* Check `payment.webhookDelivery` in the response: if it is `fail` or `pending`, the webhook was likely never received.
* Branch on `stage` or `locked` to decide whether to fulfill, hold, or release the associated product.
* Call the endpoint when you need a decision, not on a continuous polling loop.