Statü Sorgulama (Check Status)

İşlemin mevcut durumunu hızlıca öğrenmek için kullanılır. İşlem başarılı mı, beklemede mi, iptal mi edildi gibi bilgileri verir.

Ne Zaman Kullanılmalı?

• Callback alınamadığında işlem sonucunu öğrenmek için
• Timeout olan işlemlerin durumunu kontrol etmek için
• Kullanıcıya işlem durumu göstermek için
• Ödeme sonrası doğrulama yapmak için
• Webhook/callback validasyonu için

Statü Sorgulama Akışı

İşlem Statüleri (payment_status)

Statü	Açıklama	Müşteriye Göster
PENDING	İşlem beklemede (3D doğrulama devam ediyor)	"İşleminiz devam ediyor..."
COMPLETED	İşlem başarılı	"Ödeme başarılı!"
FAILED	İşlem başarısız	"Ödeme başarısız oldu"
CANCELLED	İşlem iptal edildi	"İşlem iptal edildi"
NOTFOUND	İşlem bulunamadı	"İşlem kaydı bulunamadı"
REFUND	Tam iade yapıldı	"İşlem iade edildi"
PARTIAL_REFUND	Kısmi iade yapıldı	"Kısmi iade yapıldı"

PENDING Statüsünde Polling

PENDING statüsü, 3D doğrulama sürecinde bankanın henüz sonuç döndürmediği anlamına gelir. Bu durumda işlemin tamamlanıp tamamlanmadığını öğrenmek için API'yi belirli aralıklarla tekrar çağırmanız gerekir.

İşlem sonucunu webhook ile almıyorsanız, PENDING dönüyorsa işlem henüz sonuçlanmamıştır. Müşterinize kesin bir bilgi vermeden önce statünün değişmesini bekleyin.

Önerilen Yaklaşım:

• Her 3-5 saniyede bir statüyü tekrar sorgulayın
• Statü PENDING dışına çıktığında (COMPLETED, FAILED, CANCELLED vb.) polling'i durdurun
• 15 dakikayı aşan durumlarda polling'i sonlandırın — 3D oturumu bu süre içinde sona erer

async function pollTransactionStatus(id, intervalMs = 5000, timeoutMs = 15 * 60 * 1000) {
    const startTime = Date.now();

    while (Date.now() - startTime < timeoutMs) {
        let response;

        try {
            response = await checkStatus(id);
        } catch (error) {
            // Geçici ağ/API hatası — bir sonraki döngüde tekrar dene
            await new Promise(resolve => setTimeout(resolve, intervalMs));
            continue;
        }

        const status = response.result?.payment_status;

        if (status !== 'PENDING') {
            return response; // İşlem sonuçlandı
        }

        await new Promise(resolve => setTimeout(resolve, intervalMs));
    }

    throw new Error('İşlem zaman aşımına uğradı');
}

Order Bilgileri

Başarılı işlemler için order objesi içinde önemli bilgiler bulunur:

• reference_id: Banka referans numarası (raporlamada kullanılır)
• auth_code: Banka onay kodu (dekont için gerekli)
• result_code: Banka sonuç kodu ("00" = başarılı)
• status: İşlem durumu metni

Sık Karşılaşılan Hatalar

"Transaction not found"

Neden: Girilen id veya externalId sistemde bulunamadı

Çözüm:

• ID'nin doğru olduğundan emin olun
• ID'nin tipini kontrol edin (statü sorgulamada string, detay sorgulamada integer)
• İşlemin gerçekten oluşturulduğunu doğrulayın

---

"Invalid request parameters"

Neden: Request formatı hatalı

Çözüm:

• id veya externalId alanlarından en az birini gönderin
• JSON formatının doğru olduğundan emin olun
• Veri tiplerini kontrol edin

---

Timeout Errors

Neden: API yanıt vermedi

Çözüm:

• Tekrar deneme mekanizması kurun
• Timeout süresini artırın
• Rate limit'e takılmadığınızı kontrol edin

Daha Fazla Bilgi

API detayları için: Statü Sorgulama API Referansı