> ## 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.success: Payment Confirmed Event Schema

> Reference for the payment.success webhook event, including event data, channel values, payload example, and idempotent handler implementations.

The `payment.success` event is sent when a payment is successfully confirmed. This is the signal to fulfill the order and complete the transaction in your system.

## Event Data

<ResponseField name="event" type="string" required>
  Always `payment.success`.
</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>

<ResponseField name="data.amount" type="number" required>
  The confirmed payment amount.
</ResponseField>

<ResponseField name="data.currency" type="string" required>
  The currency code.
</ResponseField>

<ResponseField name="data.paidAt" type="string" required>
  The payment confirmation timestamp in ISO 8601 format.
</ResponseField>

<ResponseField name="data.channel" type="string" required>
  The payment channel. One of: AGENCY, DELIVERY, MARKETPLACE.
</ResponseField>

## Channel Values

| Value       | Description                                           |
| ----------- | ----------------------------------------------------- |
| AGENCY      | Payment completed through an agency partner channel.  |
| DELIVERY    | Payment completed through a delivery partner channel. |
| MARKETPLACE | Payment completed through the marketplace channel.    |

## Payload Example

```json theme={null}
{
  "event": "payment.success",
  "data": {
    "reference": "ORD-2024-001",
    "paymentId": "pay_abc123xyz",
    "amount": 5000.00,
    "currency": "DZD",
    "paidAt": "2024-01-15T10:30:00Z",
    "channel": "AGENCY"
  }
}
```

## Handling This Event

<CodeGroup>
  ```javascript Node.js theme={null}
  if (event === "payment.success") {
    // Check idempotency
    const alreadyProcessed = await db.getPaymentByPaymentId(data.paymentId);
    if (alreadyProcessed) {
      return res.status(200).json({ success: true }); // already handled
    }

    await db.fulfillOrder({
      reference: data.reference,
      paymentId: data.paymentId,
      paidAt: data.paidAt,
      channel: data.channel
    });
  }
  ```

  ```python Python theme={null}
  if event == "payment.success":
      # Check idempotency
      if db.get_payment_by_payment_id(data["paymentId"]):
          return jsonify({"success": True}), 200  # already handled

      db.fulfill_order(
          reference=data["reference"],
          payment_id=data["paymentId"],
          paid_at=data["paidAt"],
          channel=data["channel"]
      )
  ```
</CodeGroup>

<Warning>
  Always check idempotency using `paymentId` before fulfilling an order. VTPE may retry delivery, and duplicate fulfillment can lead to inconsistent state.
</Warning>