Genel Hata Modeli & Kodlar

Açıklama

VPWS servisleri aşağıdaki endpoint'leri kapsar

• /vpws/paymentOptions
• /vpws/paymentOptions/{binNumber}
• /vpws/payment
• /vpws/transaction
• /vpws/payment/cancel
• /vpws/payment/refund

Servisler, işlem sonucuna göre HTTP durum kodu ve standart JSON hata modeli ile yanıt döner.

Not: /vpws/transaction servisi doğrudan Transaction nesnesi dönebilir. Hata durumlarında standart hata modeli uygulanır.

Standart Response Modeli

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

Alan Açıklamaları

Alan	Tip	Açıklama
message	string	Genel bilgi veya hata mesajı
statusCode	int	HTTP durum kodu
exceptions	object	Uygulama seviyesinde hata detayı
data	object	Başarılı işlem verisi
oldData	object	Güncellenen eski veri
errors	array	Birden fazla hata nesnesi

Hata Kodları

Kod	HTTP	Açıklama
P001	400	Geçersiz parametre
P002	401	Geçersiz veya süresi dolmuş AccessToken
P003	403	Bayi bu işlem için yetkili değil
P004	404	İşlem bulunamadı
P005	409	İşlem çakışması (tekrarlı talep)
P006	422	İşlem doğrulama hatası
P007	429	Çok fazla istek
P008	500	Sistem hatası
P009	503	Banka servisi yanıt vermedi
P010	504	Zaman aşımı
P011	600	Ödeme başarısız
P012	601	OTP doğrulama hatası
P013	602	İptal başarısız
P014	603	İade başarısız
P015	604	Kısmi iade limiti aşıldı
P016	605	Desteklenmeyen işlem
P017	606	İşlem zaten tamamlanmış
P018	607	BIN tanımsız
P019	608	POS bulunamadı
P020	609	Para birimi desteklenmiyor

Hata Yönetimi Önerileri

• statusCode ve errorCode birlikte kontrol edilmelidir.

• 200 dönse bile data.isSuccess kontrol edilmelidir.

• 429 hatasında exponential backoff önerilir.

• Banka kaynaklı hatalarda (P011–P015) retry politikası dikkatli uygulanmalıdır.