Hatalar ve durumlar
Tüm API hataları aynı zarfı kullanır. Ödemenin kendi hata bilgisi ise ödeme nesnesindeki error alanındadır.
Hata zarfı
422 Unprocessable Entity
{
"error": {
"code": "validation_failed",
"message": "İstek doğrulanamadı",
"request_id": "01J8X...",
"details": { "card.number": "geçersiz kart numarası", "installment": "1-12 arasında olmalı" }
}
}Destek talebinde request_id değerini paylaşın; isteğin tüm izine buradan ulaşılır.
HTTP durumları ve kodlar
| HTTP | code | Açıklama |
|---|---|---|
| 400 | invalid_json / invalid_body | Gövde boş ya da geçerli JSON değil. |
| 401 | unauthorized | Kimlik doğrulama başarısız. |
| 402 | — | Ödeme oluşturuldu ancak declined/failed; gövde ödeme nesnesidir. |
| 403 | forbidden | Yetki yok. |
| 404 | not_found | Kaynak yok ya da bu üye işyerine ait değil. |
| 409 | invalid_state / unsupported | Ödeme bu işlem için uygun durumda değil / sağlayıcı işlemi desteklemiyor. |
| 422 | validation_failed | details alan → mesaj haritasıdır. |
| 422 | provider_declined / provider_error | Kapama/iptal/iade işlemi bankada reddedildi ya da teknik hata verdi. |
| 429 | rate_limited | İstek sınırı aşıldı. |
| 429 | daily_limit_exceeded | Abonelik paketinizin günlük canlı işlem sınırına ulaşıldı. Sayaç Türkiye saatiyle 00:00'da sıfırlanır; details içinde limit, used ve resetsAt döner. Panelden paket yükseltebilirsiniz (paketler). |
| 500 | internal_error | Beklenmeyen hata; aynı Idempotency-Key ile yeniden deneyin. |
Ödeme hata türleri
Başarısız ödemelerde error.kind nedeni sınıflandırır:
| kind | Anlamı | Ne yapmalı |
|---|---|---|
declined | Banka reddetti (yetersiz bakiye, kart kısıtı…). Failover yapılmaz. | Müşteriye başka kart önerin. error.message banka mesajıdır. |
3ds_failed | 3D doğrulama başarısız ya da iptal edildi. | Müşteri yeniden denesin. |
technical | Bağlantı/zaman aşımı gibi geçici hata; tüm adaylar denendi. | Kısa süre sonra yeniden deneyin. |
config | POS kimlik bilgisi/yetki hatası. | Panelde hesabı doğrulayın (Doğrula düğmesi). |
no_route | Uygun POS yok: hesap, taksit, kart türü, limit ya da komisyon tanımı eşleşmedi. | Panelde yönlendirme simülasyonu ile nedenini görün. |
unsupported | Sağlayıcı bu işlemi desteklemiyor. | Sağlayıcı matrisine bakın. |
expired | 3D adımı 30 dakika içinde tamamlanmadı. | Yeni ödeme başlatın. |
Ödeme durum makinesi
| Durum | Son mu? | Açıklama |
|---|---|---|
pending | Hayır | İşleniyor ya da banka yanıtı doğrulanıyor. |
requires_action | Hayır | 3D doğrulaması bekleniyor. |
authorized | Hayır | Ön provizyon alındı; kapatılabilir/iptal edilebilir. |
captured | Hayır | Tahsil edildi; iade edilebilir. |
partially_refunded | Hayır | Kısmen iade edildi. |
refunded | Evet | Tamamen iade edildi. |
cancelled | Evet | İptal edildi. |
declined | Evet | Reddedildi. |
failed | Evet | Teknik nedenle tamamlanamadı. |