Hata Kodları

API hataları tutarlı bir standart hata yanıtı ile döner. Banka ham hata kodları (banka işlem/sonuç kodları) müşteri yüzeyine yansıtılmaz; yalnızca aşağıdaki kararlı kodları görürsünüz.

Standart hata yanıtı

{
  "error": {
    "code": "terminal_not_allowed",
    "message": "Terminal is not allowed for this partner.",
    "traceId": "trc_9f12ab"
  }
}

Alan	Açıklama
`code`	Kararlı, makine-okunur hata kodu (aşağıdaki katalog).
`message`	İnsan-okunur açıklama.
`traceId`	Destek talebinde paylaşacağınız izleme kimliği.

HTTP statü eşlemesi

Doğrulama ve iş kuralı ihlalleri → 4xx (örn. 400, 409, 422).
Kimlik doğrulama başarısız → 401.
Her hata yanıtı bir error.code ve traceId taşır.

Kod kataloğu

Kod	Anlam
`duplicate_partner_tx_code`	Aynı `partnerTxCode` ile aktif/başarılı bir ödeme zaten var.
`terminal_not_allowed`	Terminal partnere ait değil ya da pasif.
`amount_limit_exceeded`	Tutar izin verilen min/maks aralığı dışında.
`installment_not_allowed`	Kart taksite uygun değil ya da terminalin taksit izni yok.
`payment_not_refundable`	Ödeme iade için uygun durumda değil.
`refund_amount_exceeds_remaining`	İstenen iade tutarı kalan iade edilebilir bakiyeyi aşıyor.
`refund_not_yet_available`	Aynı gün kısmi iade: gün sonu sonrasında yapılabilir.
`refund_in_progress`	Bu ödeme için bekleyen bir iade zaten var (tek uçuş kuralı).

Handoff hataları

Aşağıdaki kodlar Kart Handoff sırasında, handoffUrl’e gönderilen paymentRef geçerli olmadığında oluşur. Çözüm her durumda aynıdır: yeni bir kartsız ödeme (POST /v1/payments) oluşturun ve dönen yeni paymentRef/handoffUrl ile handoff’u baştan yapın.

Kod	HTTP	Anlam
`payment_ref_invalid`	`404`	`paymentRef` geçersiz/bilinmiyor.
`payment_ref_expired`	`404`	`paymentRef`’in süresi dolmuş.
`payment_prepare_already_started`	`409`	Bu `paymentRef` için 3D zaten başlatılmış (tek-kullanım).