Genel Hata Modeli & Kodlar

Açıklama

Tüm ödeme servisleri (

• /pws/paymentSet,
• /pws/payment,
• /pws/paymentOptions,
• /pws/payment/commit,
• /pws/payment/transaction,
• /pws/payment/cancel,
• /pws/payment/refund

ortak bir hata modeline sahiptir.

Servislerden dönen tüm yanıtlar, işlem sonucuna göre HTTP durum kodu (status code) ve işlem mesajı (message) ile birlikte standart bir JSON yapısında döner.

Başarısız işlemler için isSuccess = false döner ve errorCode ile errorMessage alanları hata detayını belirtir.

Bazı hatalar hem işlem düzeyinde (data.errorCode) hem de servis genelinde (errors[]) bulunabilir.

Response Yapısı

Tüm servislerde temel dönüş yapısı aşağıdaki şekildedir

{`  
  `"message": "Açıklama metni",`  
  `"statusCode": 400,`  
  `"exceptions": null,`  
  `"data": null,`  
  `"oldData": null,`  
  `"errors": [`  
    `{`  
      `"code": "P001",`  
      `"message": "Geçersiz istek parametresi"`  
    `}`  
  `]`  
`}`

Alan Adı	Tip	Açıklama
message	string	Genel bilgi veya hata mesajı
statusCode	int	HTTP durum kodu (ör. 200, 400, 401, 404, 500)
exceptions	object	Uygulama seviyesinde yakalanan özel hata (opsiyonel)
data	object	Başarılı işlem yanıt verisi
oldData	object	Güncellenen veri senaryolarında eski kayıt bilgisi
errors	dizi	Birden fazla hata nesnesi içerebilir (code, message alanlarıyla)

Hata Kodları

Kodu	HTTP Status	Açıklama	Örnek Durum
P001	400	Geçersiz istek parametresi	Zorunlu alanlar eksik veya hatalı formatta gönderildiğinde
P002	401	Yetkisiz erişim	Geçersiz veya süresi dolmuş AccessToken
P003	403	Yetki reddedildi	Kullanıcı işlem yapmaya yetkili değil
P004	404	Kayıt bulunamadı	İptal/iade edilmek istenen referans kodu sistemde yok
P005	409	İşlem çakışması	Aynı işlem için tekrarlı talep gönderildi (ör. iki defa iade)
P006	422	İşlem doğrulama hatası	Kart numarası, BIN veya tutar geçersiz
P007	429	Çok fazla istek	Kısa sürede çok sayıda talep gönderildi
P008	500	Sistem hatası	Sunucu tarafında beklenmeyen bir hata oluştu
P009	503	Banka servisi yanıt vermedi	Provizyon sistemi veya banka API’si geçici olarak kapalı
P010	504	Zaman aşımı	Banka veya ödeme ağ geçidi yanıt süresi aşıldı
P011	600	Ödeme başarısız	Banka, işlemi reddetti (örneğin limit yetersiz, 3D başarısız)
P012	601	OTP hatası	3D Secure adımında kullanıcı doğrulaması başarısız
P013	602	İptal başarısız	İptal edilecek işlem bankadan onay alamadı
P014	603	İade başarısız	İade isteği banka tarafından reddedildi
P015	604	Kısmi iade limit aşıldı	İade toplam tutarı işlem tutarını geçti
P016	605	Desteklenmeyen işlem tipi	İstek parametrelerinde hatalı işlem tipi belirtildi
P017	606	İşlem zaten tamamlanmış	Aynı referansla tekrar işlem gönderildi
P018	607	BIN tanımsız	Gönderilen BIN numarası sistemde tanımlı değil
P019	608	POS bulunamadı	İlgili ödeme seti içinde geçerli POS tanımı yok
P020	609	Kur hata durumu	Para birimi sistemde desteklenmiyor veya dönüş oranı bulunamadı

Notlar & En İyi Uygulamalar

• StatusCode 200 dönen işlemler, sistemsel olarak başarılı sayılır. Ancak bankadan gelen işlem sonucu data.isSuccess=false olabilir.

• errorMessage kullanıcıya gösterilebilecek kısa açıklamadır. exceptions alanı ise yalnızca hata izleme/loglama içindir.

• Banka kaynaklı hatalarda (P011–P015) detaylı açıklama errorMessage alanında bulunur.

• referenceCode üzerinden yapılan işlemlerde, geçersiz kodlar için 404 - P004 hatası döner.

• Hata yönetimi sırasında, istemci tarafında statusCode ve errorCode birlikte kontrol edilmelidir.

• Tüm hata kodları geriye dönük uyumluluk için sabit tutulmalıdır.