Skip to main content
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 */ }
}
AlanAçıklama
idOlay kimliği — idempotency için kullanın. Aynı olay birden fazla kez gönderilebilir ama id aynıdır.
typeOlay tipi (payment.completed, refund.completed, vb.)
created_atOlayın Payven tarafında oluşturulma zamanı (UTC, ISO 8601)
dataOlaya özel payload — bkz. her olay altında

​
data ortak alanları

Tüm data payload’ları aşağıdaki alanları içerir (boş olabilirler):
AlanAçıklama
transaction_idİlgili işlemin Payven kimliği (UUID)
statusİşlem mevcut durumu — bkz. Payment Status
amountTutar (kuruş)
currencyPara birimi
merchant_idİşlemin merchant kimliği
provider_transaction_idBankadaki referans
auth_codeOnay kodu
error_codeHata kodu (sadece başarısız olaylarda dolu)
error_messageHata mesajı
masked_card_numberMaskelenmiş kart (örn. 454671******7894)
card_brandKart 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.