Chargeback (Ters İbraz) Yönetimi

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

Status	Anlam
`opened`	Banka chargeback açtı, merchant yanıtı bekleniyor
`disputed`	Merchant yanıt gönderdi, banka kararı bekleniyor (`merchant_response` doldurulmuş)
`won`	Lehinize karara bağlandı, tutar kalır
`lost`	Aleyhinize 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:

Kod	Açıklama (Visa/MC)
`4837`	İşlem yetkisiz (No Cardholder Authorization)
`4855`	Mal/hizmet teslim edilmedi
`4853`	Mal/hizmet kalitesinde sorun
`4863`	Cardholder Does Not Recognize
`4870`	Sahtecilik şüphesi (chip/non-chip)
`4880`	Yetkisiz 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ı

Olay	Açıklama
`chargeback.opened`	Bankadan chargeback bildirimi alındığında (kayıt oluştuğunda)
`chargeback.resolved`	Chargeback 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.

Genel Bakış

Ödeme Akışları

Sorgulamalar

Akıllı Yönlendirme

Mutabakat

Webhook'lar

Raporlama & İzleme

Test

Hata Kodları

Endpoint’ler

Liste

`status` değerleri

Manuel chargeback kaydı

Status güncelleme

Reason kodları (Visa/Mastercard)

Süre kısıtı

Önleme prensipleri

Webhook olayları

Yol haritası

​Endpoint’ler

​Liste

​status değerleri

​Manuel chargeback kaydı

​Status güncelleme

​Reason kodları (Visa/Mastercard)

​Süre kısıtı

​Önleme prensipleri

​Webhook olayları

​Yol haritası

Endpoint’ler

Liste

`status` değerleri

Manuel chargeback kaydı

Status güncelleme

Reason kodları (Visa/Mastercard)

Süre kısıtı

Önleme prensipleri

Webhook olayları

Yol haritası