Ters İbraz

Ters ibraz (chargeback / dispute), alıcının bankasının bir ödemeyi geri almasıdır — genellikle kart sahibi dolandırıcılık, ürünün teslim edilmediği ya da faturalama hatası iddiasında bulunduğu için. Chargeback API'si her itiraz için tam bir vaka yönetimi iş akışı sunar: kaydedin, sahip atayın, not tutun, kart şemasının istediği belgeleri takip edin, kanıt yükleyin, representment ile itiraza karşı savunma yapın ve vakayı bir sonuçla kapatın.

Bir ters ibraz geldiğinde payment.disputed webhook'u tetiklenir (chargebackId, disputeState ve itiraz edilen tutarı taşır) — sistemleriniz durumu birinin banka portalını kontrol etmesini beklemeden, olduğu anda öğrenir. Ödemenin finansal durumu (CAPTURED/REFUNDED) itirazla ezilmez.

Tüm chargeback endpointleri düz Bearer kimlik doğrulaması kullanır (at_live_… erişim token'ı); para hareketi değil, vaka kaydı yönetirler.

Tüm tutarlar minor-unit (kuruş) taşınır: chargeback gövdesinde "amountMinor": "10050" = ₺100,50 (string).

Yaşam döngüsü

Bir itiraz vakası basit bir yaşam döngüsünden geçer:

Alındı — vaka oluşturulur (POST /chargebacks) ve ödemeye bağlanır (vaka durumu RECEIVED).
İşleniyor — ekibiniz vakayı yürütür: atama, notlar, belge talepleri, kanıtlar (UNDER_REVIEW).
Representment gönderildi (opsiyonel) — kanıtlarınızla birlikte representment göndererek ters ibraza resmen itiraz edersiniz (REPRESENTMENT_SUBMITTED).
Çözüldü — vaka üç sonuçtan biriyle kapanır:

Sonuç	Anlamı
`WON`	Representment başarılı — para size geri döner
`LOST`	İtiraz kart sahibi lehine sonuçlandı — para geri alınmış kalır
`ACCEPTED`	Ters ibraza itiraz etmemeyi seçtiniz ve geri alınmayı kabul ettiniz

Endpointler

Method	Path	Ne yapar
POST	`/chargebacks`	Bir ödemeye karşı yeni itiraz vakası kaydeder
GET	`/chargebacks`	İtiraz vakalarını listeler
GET	`/chargebacks/:id`	Vakanın tam detayı
PATCH	`/chargebacks/:id/status`	Vakanın yaşam döngüsü durumunu günceller
POST	`/chargebacks/:id/assign`	Vakayı bir ekip üyesine atar
POST	`/chargebacks/:id/notes`	Vaka zaman çizelgesine iç not ekler
POST	`/chargebacks/:id/document-requests`	Şemanın/bankanın istediği bir belgeyi takibe alır
POST	`/chargebacks/:id/evidence`	Vakaya kanıt belgesi yükler
POST	`/chargebacks/:id/representment`	Representment gönderir (ters ibraza resmen itiraz)
POST	`/chargebacks/:id/resolve`	Vakayı bir sonuçla kapatır: `WON`, `LOST` veya `ACCEPTED`

Bir itirazı yürütme

İtirazdan haberdar olun

payment.disputed webhook'unuz chargebackId ve disputeState ile tetiklenir. Vakayı kaydedin (buradaki tutar minor-unit string'dir):

curl -X POST https://api-gateway.lunixi.com/api/v1/chargebacks \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "paymentId": "pay_9f3a1c",
    "amountMinor": "10050",
    "currency": "TRY",
    "networkReasonCode": "13.1",
    "reasonCategory": "product_not_received"
  }'

Opsiyonel alanlar: provider, providerCaseId, cycleCount, representmentDeadline (ISO tarih) ve ücret alanları. Vakalar provider + providerCaseId + cycle (manuel girişte paymentId + cycle) üzerinden dedupe edilir — aynı itirazı tekrar POST etmek mevcut vakayı created: false ile döndürür.

Sahip atayın ve inceleyin

Vakayı yürütecek kişiye atayın ve incelemeyi kayıt altında tutun:

curl -X POST https://api-gateway.lunixi.com/api/v1/chargebacks/cb_5d21e0/assign \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "assignedUserId": "usr_ops_17", "priority": "HIGH" }'
 
curl -X POST https://api-gateway.lunixi.com/api/v1/chargebacks/cb_5d21e0/notes \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "note": "Sipariş 2026-06-28 kargolandı, takip teslim edildi gösteriyor. Kurye tutanağı isteniyor." }'

Şemanın istediklerini toplayın

Banka ya da şema belirli belgeler isterse her birini POST /chargebacks/:id/document-requests ile ({ "requestType": "…", "description": "…", "dueDate": "…" }) takibe alın, sonra kanıt ekleyerek karşılayın. Kanıt, daha önce yüklenmiş bir dosyaya referans veren (fileRef) bir JSON kaydıdır; aynı type ile yeniden gönderim versiyonlanır:

curl -X POST https://api-gateway.lunixi.com/api/v1/chargebacks/cb_5d21e0/evidence \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DELIVERY",
    "fileRef": "media/disputes/cb_5d21e0/teslimat-tutanagi.pdf",
    "fileName": "teslimat-tutanagi.pdf",
    "mimeType": "application/pdf",
    "note": "İmzalı kurye teslimat onayı"
  }'

İtiraz edin — ya da kabul edin

Ters ibraza karşı savunma yapmak için representment gönderin (gövde yok — vakanın mevcut kanıt seti neyse o sunulur):

curl -X POST https://api-gateway.lunixi.com/api/v1/chargebacks/cb_5d21e0/representment \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

İtiraz haklıysa (ya da uğraşmaya değmiyorsa) bu adımı atlayın ve vakayı ACCEPTED olarak kapatın.

Vakayı kapatın

Şemanın kararı geldiğinde vakayı sonuçlandırın:

curl -X POST https://api-gateway.lunixi.com/api/v1/chargebacks/cb_5d21e0/resolve \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "WON", "reason": "Teslimat kanıtı kabul edildi" }'

Yanıt biçimi

Mutasyon çağrıları kompakt bir vaka referansıyla yanıt verir:

{
  "id": "cb_5d21e0",
  "caseNumber": "CB-000123",
  "status": "UNDER_REVIEW",
  "created": false
}

GET /chargebacks/:id, vakanın tam detayını döner — vaka kaydı (ödeme bağlantısı, amountMinor, sebep kodları, atama, öncelik, son tarihler) artı zaman çizelgesi, checklist, kanıtlar, notlar ve görevler. Vaka status değerleri: RECEIVED, UNDER_REVIEW, REPRESENTMENT_SUBMITTED, WON, LOST, ACCEPTED, CLOSED.

İş akışınız açık bir aşama değişikliği gerektirdiğinde vakayı PATCH /chargebacks/:id/status ile { "toStatus": "UNDER_REVIEW" } (veya "REPRESENTMENT_SUBMITTED") göndererek ilerletin; itiraz kuyruğunuzu GET /chargebacks (Bearer, sayfalanmış) ile kurun.

Hatalar

Durum	Ne olur / ne yapmalı
Bilinmeyen chargeback veya ödeme id'si	`404` — id'yi kontrol edin; vakalar merchant kapsamındadır.
Zaten çözülmüş vakayı çözme	Durum-çakışması hatası — bir vaka yalnızca tek bir nihai sonuç alır.
Geçersiz `outcome` değeri	Doğrulama hatası — `WON`, `LOST` veya `ACCEPTED` değerlerini birebir kullanın.
Kanıt yüklemesi reddedildi	Dosya boyutunu/biçimini kontrol edip tekrar deneyin; her yükleme çağrısında tek belge gönderin.
Eksik veya geçersiz API key	`401` — chargeback endpointleri sunucu tarafı Bearer key ister.

Webhooks

Event	Ne zaman tetiklenir
`payment.disputed`	Bir ödemeye ters ibraz açıldığında veya faz değiştirdiğinde — `chargebackId`, `disputeState`, `disputedAmountMinor`, `openChargebackCount` taşır

payment.disputed geldiğinde iç vakanızı hemen açın: itiraz pencereleri kısadır ve erken toplanan kanıt vakayı kazandırır.

Sonraki adımlar

Webhooks — payment.disputed arkasındaki teslimat modeli
Ödemeleri Listeleme — itiraz edilen ödemeyi ve geçmişini bulun
İadeler — proaktif iade, itirazın hiç açılmamasını sağlayabilir

Webhook'lar Genel Bakış