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

# Webhook Olay Kataloğu

> Sanal POS'un yayınladığı tüm webhook olayları ve payload alanları.

Sanal POS şu anda **18 olay tipi** yayınlar (ödeme/iade/iptal + 3DS + Pre-Auth + Recurring + Chargeback + Settlement). Subscription oluştururken `events[]` dizisinde dinlemek istediklerinizi belirtirsiniz.

## Genel yapı

Tüm olaylar şu yapıda gönderilir:

```json theme={null}
{
  "id":         "evt_8e3f5c129a7b4c8dbc4e",
  "type":       "payment.completed",
  "created_at": "2026-05-03T12:34:58.123+00:00",
  "data": { /* olaya özel payload — aşağıda */ }
}
```

| Alan         | Açıklama                                                                                                  |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| `id`         | Olay kimliği — idempotency için kullanın. **Aynı olay birden fazla kez gönderilebilir** ama `id` aynıdır. |
| `type`       | Olay tipi (`payment.completed`, `refund.completed`, vb.)                                                  |
| `created_at` | Olayın Payven tarafında oluşturulma zamanı (UTC, ISO 8601)                                                |
| `data`       | Olaya özel payload — bkz. her olay altında                                                                |

## `data` ortak alanları

Tüm `data` payload'ları aşağıdaki alanları içerir (boş olabilirler):

| Alan                      | Açıklama                                                                                |
| ------------------------- | --------------------------------------------------------------------------------------- |
| `transaction_id`          | İlgili işlemin Payven kimliği (UUID)                                                    |
| `status`                  | İşlem mevcut durumu — bkz. [Payment Status](/sanal-pos/payment-object#status-degerleri) |
| `amount`                  | Tutar (kuruş)                                                                           |
| `currency`                | Para birimi                                                                             |
| `merchant_id`             | İşlemin merchant kimliği                                                                |
| `provider_transaction_id` | Bankadaki referans                                                                      |
| `auth_code`               | Onay kodu                                                                               |
| `error_code`              | Hata kodu (sadece başarısız olaylarda dolu)                                             |
| `error_message`           | Hata mesajı                                                                             |
| `masked_card_number`      | Maskelenmiş kart (örn. `454671******7894`)                                              |
| `card_brand`              | Kart birliği (`visa`, `mastercard`, `troy`, `amex`)                                     |

## Olay tipleri

### `payment.completed`

**Tetikleyici:** Sale akışı (Non-3D veya 3DS sonrası) başarıyla tamamlandığında.

```json theme={null}
{
  "id":         "evt_...",
  "type":       "payment.completed",
  "created_at": "2026-05-03T12:34:58.123+00:00",
  "data": {
    "transaction_id":          "8e3f5c12-...",
    "status":                  "completed",
    "amount":                  15000,
    "currency":                "TRY",
    "merchant_id":             "3fa85f64-...",
    "provider_transaction_id": "9f3d2b8e-...",
    "auth_code":               "123456",
    "error_code":              null,
    "error_message":           null,
    "masked_card_number":      "454671******7894",
    "card_brand":              "visa"
  }
}
```

### `payment.failed`

**Tetikleyici:** Banka tarafı reddi veya teknik hata.

```json theme={null}
{
  "id":         "evt_...",
  "type":       "payment.failed",
  "created_at": "2026-05-03T12:34:58.123+00:00",
  "data": {
    "transaction_id":     "8e3f5c12-...",
    "status":             "failed",
    "amount":             15000,
    "currency":           "TRY",
    "merchant_id":        "3fa85f64-...",
    "auth_code":          null,
    "error_code":         "bank_declined",
    "error_message":      "Yetersiz bakiye",
    "masked_card_number": "454671******7894",
    "card_brand":         "visa"
  }
}
```

### `payment.authorized`

**Tetikleyici:** Pre-Auth (ön provizyon) başarıyla alındığında. Tutar bloke edildi, henüz çekilmedi.

```json theme={null}
{
  "type": "payment.authorized",
  "data": {
    "transaction_id": "8e3f5c12-...",
    "status":         "authorized",
    "amount":         50000,
    "currency":       "TRY",
    "auth_code":      "123456"
  }
}
```

### `capture.completed`

**Tetikleyici:** Pre-Auth → Capture başarıyla tamamlandığında.

```json theme={null}
{
  "type": "capture.completed",
  "data": {
    "transaction_id": "8e3f5c12-...",
    "status":         "completed",
    "amount":         47500,
    "currency":       "TRY",
    "auth_code":      "789012"
  }
}
```

### `void.completed`

**Tetikleyici:** İşlem void edildiğinde (mutabakat öncesi tam iptal). Pre-Auth iptalinde de bu olay yayınlanır.

```json theme={null}
{
  "type": "void.completed",
  "data": {
    "transaction_id":          "8e3f5c12-...",
    "status":                  "canceled",
    "provider_transaction_id": "VOID-9f3d2b8e"
  }
}
```

### `refund.completed`

**Tetikleyici:** İade başarıyla yapıldığında (tam veya kısmi).

```json theme={null}
{
  "type": "refund.completed",
  "data": {
    "transaction_id":          "8e3f5c12-...",
    "status":                  "completed",
    "amount":                  5000,
    "currency":                "TRY",
    "provider_transaction_id": "REFUND-9f3d2b8e"
  }
}
```

`status` alanı işlemin **mevcut** durumunu yansıtır: kısmi iade için ana Transaction `completed` kalır (iade alt-Transaction olarak ayrı yazılır), tüm tutar iade edildiğinde ana Transaction `refunded` olur.

### `3ds.completed`

**Tetikleyici:** 3D Secure doğrulaması başarılı + bankada otorizasyon başarılı.

```json theme={null}
{
  "type": "3ds.completed",
  "data": {
    "transaction_id": "8e3f5c12-...",
    "status":         "completed",
    "amount":         15000,
    "currency":       "TRY",
    "auth_code":      "123456"
  }
}
```

### `3ds.failed`

**Tetikleyici:** 3DS doğrulaması başarısız (yanlış SMS, timeout, kullanıcı iptali) veya 3DS sonrası banka reddi.

```json theme={null}
{
  "type": "3ds.failed",
  "data": {
    "transaction_id": "8e3f5c12-...",
    "status":         "failed",
    "error_code":     "three_ds_authentication_failed",
    "error_message":  "3D Secure doğrulaması başarısız."
  }
}
```

## Recurring (subscription) olayları

### `subscription.charged`

**Tetikleyici:** Tekrarlayan ödeme planının bir taksiti başarıyla çekildiğinde. Her başarılı taksit için ayrıca `payment.completed` da yayınlanır.

```json theme={null}
{
  "type": "subscription.charged",
  "data": {
    "recurring_plan_id":    "plan-...",
    "installment_index":    3,
    "transaction_id":       "8e3f5c12-...",
    "status":               "completed",
    "amount":               15000,
    "currency":             "TRY"
  }
}
```

### `subscription.failed`

**Tetikleyici:** Bir taksit başarısız olduğunda (kart bakiyesi, banka reddi). Plan otomatik askıya alınmaz.

### `subscription.cancelled`

**Tetikleyici:** Kullanıcı veya operatör planı iptal ettiğinde (`POST /recurring/{id}/cancel`).

### `subscription.completed`

**Tetikleyici:** Planın tüm taksitleri başarıyla tamamlandığında.

### `subscription.charge.reversed`

**Tetikleyici:** Daha önceden başarıyla çekilmiş bir taksit, provider tarafında **tersine çevrildiğinde** (same-day void / reversal). İlişkili Transaction için ayrıca `void.completed` da fire eder.

### `subscription.charge.failed`

**Tetikleyici:** Daha önceden başarıyla çekilmiş bir taksit provider sonradan **Error** olarak raporladığında (provider correction). İlişkili Transaction için ayrıca `payment.failed` fire eder.

## Chargeback (ters ibraz) olayları

### `chargeback.opened`

**Tetikleyici:** Bankadan bir chargeback (ters ibraz) bildirimi alındığında.

```json theme={null}
{
  "type": "chargeback.opened",
  "data": {
    "chargeback_id":    "cbk-...",
    "transaction_id":   "8e3f5c12-...",
    "amount":           15000,
    "currency":         "TRY",
    "reason_code":      "fraud_suspected",
    "due_date":         "2026-05-15T23:59:59+00:00"
  }
}
```

### `chargeback.resolved`

**Tetikleyici:** Chargeback sonuçlandığında — kabul, ret veya delil sunma süreci tamamlandığında.

## Settlement olayları

### `settlement.created`

**Tetikleyici:** Bir gün/dönem için settlement kaydı oluşturulduğunda.

```json theme={null}
{
  "type": "settlement.created",
  "data": {
    "settlement_id":    "stl-...",
    "period_start":     "2026-05-03T00:00:00+00:00",
    "period_end":       "2026-05-03T23:59:59+00:00",
    "total_amount":     1850000,
    "transaction_count":127
  }
}
```

### `settlement.completed`

**Tetikleyici:** Settlement işlemi (bankaya ödenmiş, mutabakat onaylanmış) tamamlandığında.

## Olay → İşlem durumu eşleşmesi

```mermaid theme={null}
stateDiagram-v2
    [*] --> created
    created --> authorized: payment.authorized (PreAuth)
    created --> completed: payment.completed (Sale)
    created --> failed: payment.failed
    created --> three_d_secure_init_processing: 3DS init
    three_d_secure_init_processing --> completed: 3ds.completed
    three_d_secure_init_processing --> failed: 3ds.failed
    authorized --> completed: capture.completed
    authorized --> canceled: void.completed
    completed --> canceled: void.completed (gün içi)
    completed --> refunded: refund.completed (tam)
    completed --> completed: refund.completed (kısmi — alt-Tx ayrı yazılır)
```

## Webhook subscription örneği

```bash theme={null}
curl -X POST https://vpos.payven.com.tr/api/v1/webhook-subscriptions \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://example.com/webhooks/payven",
    "events": [
      "payment.completed",
      "payment.failed",
      "payment.authorized",
      "capture.completed",
      "void.completed",
      "refund.completed",
      "3ds.completed",
      "3ds.failed"
    ]
  }'
```

Tüm olaylara abone olmak için `["*"]` kullanmayın — açık liste tutmak ileride yeni olay tiplerini bilinçli almanızı sağlar (mevcut handler'ınızda olmayan olay tipleri unhandled error fırlatmasın).

## Yol haritası

İleride eklenmesi planlanan olaylar:

* `connector.health_changed` — banka sağlık durumu değişti (circuit breaker open/close)
* `reconciliation.discrepancy_detected`, `reconciliation.finalized` — mutabakat olayları

Güncellemeler için [Changelog](/resources/changelog) sayfasını izleyin.