Webhook Olay Kataloğu

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:

{
  "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
`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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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).

{
  "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ı.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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

Webhook subscription örneği

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 sayfasını izleyin.

Genel Bakış

Ödeme Akışları

Sorgulamalar

Akıllı Yönlendirme

Mutabakat

Webhook'lar

Raporlama & İzleme

Test

Hata Kodları

Genel yapı

`data` ortak alanları

Olay tipleri

`payment.completed`

`payment.failed`

`payment.authorized`

`capture.completed`

`void.completed`

`refund.completed`

`3ds.completed`

`3ds.failed`

Recurring (subscription) olayları

`subscription.charged`

`subscription.failed`

`subscription.cancelled`

`subscription.completed`

`subscription.charge.reversed`

`subscription.charge.failed`

Chargeback (ters ibraz) olayları

`chargeback.opened`

`chargeback.resolved`

Settlement olayları

`settlement.created`

`settlement.completed`

Olay → İşlem durumu eşleşmesi

Webhook subscription örneği

Yol haritası

​Genel yapı

​data ortak alanları

​Olay tipleri

​payment.completed

​payment.failed

​payment.authorized

​capture.completed

​void.completed

​refund.completed

​3ds.completed

​3ds.failed

​Recurring (subscription) olayları

​subscription.charged

​subscription.failed

​subscription.cancelled

​subscription.completed

​subscription.charge.reversed

​subscription.charge.failed

​Chargeback (ters ibraz) olayları

​chargeback.opened

​chargeback.resolved

​Settlement olayları

​settlement.created

​settlement.completed

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

​Webhook subscription örneği

​Yol haritası

Genel yapı

`data` ortak alanları

Olay tipleri

`payment.completed`

`payment.failed`

`payment.authorized`

`capture.completed`

`void.completed`

`refund.completed`

`3ds.completed`

`3ds.failed`

Recurring (subscription) olayları

`subscription.charged`

`subscription.failed`

`subscription.cancelled`

`subscription.completed`

`subscription.charge.reversed`

`subscription.charge.failed`

Chargeback (ters ibraz) olayları

`chargeback.opened`

`chargeback.resolved`

Settlement olayları

`settlement.created`

`settlement.completed`

Olay → İşlem durumu eşleşmesi

Webhook subscription örneği

Yol haritası