Skip to main content
Chargeback, kart sahibinin bankasına başvurarak işlemi reddetmesi durumunda bankanın size karşı açtığı geri alma talebidir. Cevap vermez veya kaybederseniz tutar hesabınızdan çekilir.
Şu anda Payven chargeback kayıt + status takibi destekler — ham yanıt evrakının bankaya iletimi konnektör + banka iş süreçleri üzerinden gerçekleştirilir. Programatik “respond + evidence upload” akışı yol haritasındadır.

​
Endpoint’ler

GET    /api/v1/chargebacks                  # Liste (sayfalı)
GET    /api/v1/chargebacks/{id}             # Tek chargeback detayı
POST   /api/v1/chargebacks                  # Manuel chargeback kaydı (banka tarafından bildirilen)
PUT    /api/v1/chargebacks/{id}/status      # Durum güncelle
Bearer access token gerektirir (OAuth 2.0 Client Credentials).

​
Liste

curl "https://vpos.payven.com.tr/api/v1/chargebacks?status=open&page=1&page_size=20" \
  -H "Authorization: Bearer $PAYVEN_TOKEN"

{
  "items": [
    {
      "id":                "9f3d2b8e-...",
      "transaction_id":    "8e3f5c12-...",
      "amount":            15000,
      "currency":          "TRY",
      "reason":            "İşlem yetkisiz",
      "reason_code":       "4837",
      "bank_reference_no": "CB-GAR-789",
      "status":            "opened",
      "response_deadline": "2026-05-22T23:59:59.000+00:00",
      "resolved_at":       null,
      "merchant_response": null,
      "notes":             null,
      "created":           "2026-05-15T10:30:00.000+00:00"
    }
  ],
  "page":              1,
  "total_pages":       1,
  "total_count":       3,
  "has_previous_page": false,
  "has_next_page":     false
}

​
status değerleri

StatusAnlam
openedBanka chargeback açtı, merchant yanıtı bekleniyor
disputedMerchant yanıt gönderdi, banka kararı bekleniyor (merchant_response doldurulmuş)
wonLehinize karara bağlandı, tutar kalır
lostAleyhinize karara bağlandı, tutar düşüldü

​
Manuel chargeback kaydı

Banka chargeback bildirimini Payven dışından (e-posta, banka portalı) aldıysanız sisteme manuel kaydedebilirsiniz: 
curl -X POST https://vpos.payven.com.tr/api/v1/chargebacks \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: cb-bank-ref-789" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id":    "8e3f5c12-...",
    "amount":            15000,
    "currency":          "TRY",
    "reason":            "İşlem yetkisiz",
    "reason_code":       "4837",
    "response_deadline": "2026-05-22T23:59:59+00:00",
    "bank_reference_no": "CB-GAR-789"
  }'

​
Status güncelleme

Bankaya yanıt gönderdikten veya banka kararını öğrendikten sonra: 
curl -X PUT https://vpos.payven.com.tr/api/v1/chargebacks/9f3d2b8e.../status \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status":            "disputed",
    "merchant_response": "Müşteri ile yazışmalar + kargo teslim fişi banka portalına yüklendi (REF: ABC-123)",
    "notes":             "Banka portal evrak no: 2026-04-789"
  }'
merchant_response alanı bankaya iletilecek dispute içeriği; notes operatör notları için kalıcı saklanır — audit/dispute süreci için kritik.

​
Reason kodları (Visa/Mastercard)

Sık karşılaşılan kodlar:
KodAçıklama (Visa/MC)
4837İşlem yetkisiz (No Cardholder Authorization)
4855Mal/hizmet teslim edilmedi
4853Mal/hizmet kalitesinde sorun
4863Cardholder Does Not Recognize
4870Sahtecilik şüphesi (chip/non-chip)
4880Yetkisiz tekrar tahsilat
Tam liste için banka anlaşma dokümanlarınıza veya kart şeması sözlüğüne (Visa Reason Codes / MC Chargeback Reason Codes) bakın.

​
Süre kısıtı

Chargeback’lere genellikle 7 gün içinde yanıt verilmesi beklenir (banka anlaşmanıza göre değişir). Süreyi geçirirseniz banka çoğu durumda otomatik müşteri lehine karar verir.

​
Önleme prensipleri

3D Secure kullanın — başarılı 3DS sonrası chargeback sorumluluğu bankaya geçer (özellikle 4837 kategorisi için kritik).
Müşteri iletişim kayıtlarını saklayın — yazışmalar, sipariş onayı, teslim kanıtı.
Net merchant adı — kart ekstresinde müşterinin tanıyacağı isim kullanın (Acme Magaza yerine XYZ Bilgi Tek müşteriyi şüpheye düşürür).
Hızlı iade politikası — müşteri sizden iade alabilse chargeback açmaz; en pratik chargeback önleme yolu.
Fraud kuralları — yüksek riskli işlemleri önceden işaretleyin (kurallar konsol → Fraud ekranından yönetilir).

​
Webhook olayları

OlayAçıklama
chargeback.openedBankadan chargeback bildirimi alındığında (kayıt oluştuğunda)
chargeback.resolvedChargeback sonuçlandığında (won/lost)
Detay: Webhook Olay Kataloğu.

​
Yol haritası

  • Programatik evidence upload — POST /chargebacks/{id}/evidence (PDF/JPG attach)
  • Visa/MC reason kodu kataloğu — konsoldan açıklama görüntüleme
Güncellemeler için: Changelog.