> ## 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.

# Chargeback (Ters İbraz) Yönetimi

> Müşteri bankası tarafından açılan ters ibraz dosyalarını izleyin ve yönetin.

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.

<Note>
  Ş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.
</Note>

## Endpoint'ler

```http theme={null}
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

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

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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

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

## 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](/sanal-pos/webhooks/events#chargeback-ters-ibraz-olaylar).

## 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](/resources/changelog).