Skip to main content

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’lar, ödeme yaşam döngüsünün asenkron olaylarını sunucunuza anlık iletir: 3DS sonrası ödeme tamamlandığında, banka iadeyi onayladığında, mutabakat oluştuğunda.
Bu sayfa Sanal POS özelinde webhook detaylarını anlatır. Genel webhook prensipleri için: Webhook Genel Bakış (Documentation).

​
Abone olma

POST /api/v1/webhooks

curl -X POST https://vpos.payven.com.tr/api/v1/webhooks \
  -H "X-API-Key: $KEY" -H "X-API-Secret: $SECRET" -H "X-Merchant-Id: $MERCHANT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/payven",
    "events": [
      "payment.succeeded",
      "payment.failed",
      "payment.voided",
      "refund.succeeded",
      "refund.failed",
      "reconciliation.completed"
    ],
    "active": true
  }'
AlanTipAçıklama
urlstringHTTPS endpoint’iniz
eventsstring[]Abone olunan olay tipleri. Tüm olaylar için ["*"].
activeboolPasifleştirme için false

​
Yanıt

{
  "isSuccess": true,
  "code": "201",
  "data": {
    "id": "wh_8e3f5c12",
    "url": "https://api.example.com/webhooks/payven",
    "events": ["payment.succeeded", ...],
    "secret": "whsec_8e3f5c12_9a7b4c8dbc4e2c963f66afa6",
    "active": true,
    "createdAt": "2026-05-03T12:00:00Z"
  }
}
secret yalnızca yanıtta bir kez döner. Hemen secret manager’a kaydedin — imza doğrulamada kullanacaksınız.

​
Olay listesi

Tüm olayların kataloğu → Özet:
KategoriOlaylar
Ödemepayment.succeeded, payment.failed, payment.authorized, payment.captured, payment.voided
3D Securepayment.threeds.initialized, payment.threeds.authenticated, payment.threeds.failed
İaderefund.succeeded, refund.failed
Hosted Checkoutcheckout.session.completed, checkout.session.expired, checkout.session.failed
Pay-by-Linkpayment.link.created, payment.link.viewed, payment.link.expired
Mutabakatreconciliation.created, reconciliation.completed, reconciliation.discrepancy
Sistemwebhook.test, plan.usage.warning

​
İmza doğrulama

Her gelen webhook isteği X-Payven-Signature başlığı ile imzalanır. Detay ve kod örnekleri: İmza Doğrulama.

​
Yeniden deneme

Endpoint’iniz 2xx dönmezse Payven 5 kez yeniden dener: 1m, 5m, 30m, 2h, 24h. Detay: Yeniden Deneme Politikası.

​
Abonelikleri yönetme

# Liste
GET /api/v1/webhooks

# Detay
GET /api/v1/webhooks/{id}

# Güncelleme
PUT /api/v1/webhooks/{id}

# Secret rotasyonu
POST /api/v1/webhooks/{id}/rotate-secret

# Silme
DELETE /api/v1/webhooks/{id}

# Teslim kayıtları
GET /api/v1/webhooks/{id}/deliveries

​
Teslim kayıtları

Konsol → Webhook Teslim Kayıtları ekranından her teslim denemesinin:
  • HTTP yanıt kodunu
  • Yanıt gövdesini
  • Süresini (ms)
  • Yeniden deneme sayısını
  • Tam request/response payload’unu
görebilirsiniz. Sorun gidermede ilk başvurulacak yer burasıdır.

​
Test webhook’u gönderme

İmza ve endpoint doğrulamak için: 
curl -X POST https://vpos.payven.com.tr/api/v1/webhooks/{id}/test \
  -H "X-API-Key: $KEY" -H "X-API-Secret: $SECRET" -H "X-Merchant-Id: $MERCHANT"
Endpoint’inize webhook.test tipinde bir olay gönderir.