Hata Grupları

Craftgate API, bir işlem ya da sorgu yürütülürken sistemsel ya da kurgusal bir hata oluşması durumunda belli formatta bir cevap döner. API dokümantasyonu giriş sayfasındaki Hatalı İşlemler bölümünde de belirtildiği üzere bu gibi durumlarda dönecek cevap içerisinde yalnızca errors isimli bir alan yer alır. Oluşan hataya ilişkin detayları içeren bu objenin parametreleri aşağıdaki gibidir:

Parametre Adı Tipi Her Zaman Mevcut Açıklama
errorCode string Evet Hataya ilişkin ayrıştırıcı kod numarası
errorDescription string Evet Hatanın niteliğini ifade eden açıklayıcı mesaj
errorGroup string Hayır (Bkz: Ödeme Hata Grupları) Ödemeye ilişkin bir hata gerçekleştiği durumda gönderilen hata grubu

Bir hata durumunda üye işyerleri kendi taraflarındaki iş kurallarını yürütmek ve/veya kullanıcıya göre yerelleştirilmiş hata mesajları gösterebilmek için errorCode ve errorGroup alanlarından faydalanabilir.

Önemli Not: Ödeme ile ilgili hatalar için mutlak suretle errorGroup alanını kullanınız.

Örnek 1 Kredi kartı limiti yetersiz hatası alınan bir ödeme denemesi için dönülen hata:

{
    "errors": {
        "errorCode": "10051",
        "errorDescription": "Kart limiti yetersiz, yetersiz bakiye",
        "errorGroup": "NOT_SUFFICIENT_FUNDS"
    }
}

Örnek 2 Girilen kart bilgilerindeki son kullanım tarihi alanının hatalı olduğu durumda dönülen hata:

{
    "errors": {
        "errorCode": "4152",
        "errorDescription": "Kart son kullanma yılı \"2010\" geçersiz"
    }
}

Hata Grupları

Craftgate tarafından dönen hatalardan, hata kodu 10000den büyük olanlar ödeme hataları, 10000den küçük olanlar validasyon hatalarıdır.

Validasyon Hataları (Entegrasyon Kaynaklı)

Craftgate API, ödeme alma, iptal/iade uygulama gibi işlemlerde, banka ya da ödeme kuruluşu ile iletişim kurmadan önce, üye işyeri tarafından iletilmiş olan istek parametrelerini çeşitli kontrollerden geçirir. Bu kontroller esnasında, hatalı biçimlendirilmiş ya da iş kurallarına uygun olmayan bir parametre tespit edildiğinde (hatalı kart numarası, geçmiş tarihli son kullanım tarihi, eksik ödeme bilgisi, vb.) istek validasyon hatası olarak işaretlenir ve bir hata mesajı döner. Bu tür hatalar, hata kodları 10000den küçük hatalardır. Bu hataların error group değeri dönülmez.

Ödeme başarım oranlarınızı olabildiğince yüksek tutabilmeniz için canlıya geçiş yapmadan önce bu gibi hataları önceden tespit edip, sistemlerinizi bu hatalarla karşılaşmayacak şekilde kurgulamanız önerilir. Entegrasyon başarılı bir biçimde tamamlanmışsa canlı ortamda hiç görülmemesi beklenir. Ancak olası entegrasyon sorunlarının kullanıcının önüne düşmemesi için, Craftgate ile entegre olan üye işyerleri, 10000den küçük hata kodlarına sahip hataları yakalamalı ve kullanıcıya yansıtmamalıdır.

Ödeme Hataları (Ödeme Kaynaklı)

Ödemeye ilişkin hatalar, errorGroup değerleri ve açıklamaları ile aşağıdaki tabloda listelenmiştir. Bu hata grupları bankalardan ve ödeme ve e-para kuruluşlarından Craftgate'e dönen hata mesajlarına uygun olarak tasarlanmıştır. Burada listelenen her bir hata grubu 10xxx formatında bir koda (errorCode) sahiptir.

Hata Grubu (errorGroup) Açıklama Detay
AMEX_CAN_USE_ONLY_MR American Express kart hatası American Express kart ile işlem yapılırken hata oluştu.
APM_ERROR APM Ödemesi alınamadı APM Ödemesi alınamadı.
APPROVED_COMPLETED Önceden onaylanan işlem Ödemede kullanılan sipariş numarası (orderId) daha önce başarılı başka bir ödeme sırasında kullanılmıştır. Başarılı geçen ödeme kontrol edilmeli, eğer ödeme gerçekleşmediğini düşünüyorsanız yeni bir sipariş numarası ile ödeme tekrar denenmelidir.
BIN_NOT_FOUND BIN bulunamadı Kart numarasının ilk 8 hanesi BIN numarasını belirlemektedir. Girilen kart numarasından geçerli bir BIN numarası bulunamamıştır. Müşteri kart numarasını kontrol edip tekrar ödeme denemesi yapmalıdır.
BLOCKED_CARD Bloke statülü kart Kart bankası tarafından kartın blokeli olduğu bilgisi iletilmiştir. Müşteri, bankası ile iletişime geçmelidir.
CARD_NOT_PERMITTED Kart, işleme izin vermedi Kart bankası tarafından bu kart ile ilgili işlem yapılamayacağı bilgisi iletilmiştir. Ödeme farklı bir kart ile denenebilir.
COMMUNICATION_OR_SYSTEM_ERROR İletişim veya sistem hatası Banka beklenen sürede cevap veremedi, bankada anlık bir kesinti yaşanmış olabilir.
CVC2_MAX_ATTEMPT CVC2 yanlış girme deneme sayısı aşıldı Kart numarasına ait güvenlik kodu üst üste hatalı girilmiştir ve hatalı giriş deneme sayısı aşıldığı için işlem reddedilmiştir.
CVC_REQUIRED CVC gönderilmesi zorunludur POS üzerinden CVC güvenlik kodu olmadan ödeme geçirilemez. Güvenlik kodu CVC değerinin girildiğinden emin olarak ödeme tekrar denenmelidir.
DEBIT_CARDS_INSTALLMENT_NOT_ALLOWED Banka kartları ile taksit yapılamaz Banka hesap kartları (debit kartlar) ile taksitli işlem yapılamaz. Ödemenin başarılı geçmesi için tek çekim işlem denenmelidir.
DEBIT_CARDS_REQUIRES_3DS Banka kartları sadece 3D Secure işleminde kullanılabilir Banka hesap kartları (debit kartlar) ile 3D Secure ödeme yapılmalıdır. Müşteri kart numarası olarak hesap kartı girdiyse, 3D Secure ödemeye yönlendirilmelidir.
DECLINED Ödeme alınamadı Ödeme alınamadı. Kart sahibi, bankası ile görüşmelidir.
DO_NOT_HONOUR İşlem onaylanmadı. Lütfen başka kart ile deneyiniz Kart sahibinin bankası ödemeyi onaylamadı. Günlük işlem limiti/adedi aşılmış veya arka arkaya bir çok deneme yapıldığı için hata alınmış olabilir. Müşteri, bankası ile iletişime geçmelidir.
EXCEEDS_ALLOWABLE_PIN_TRIES İzin verilen PIN giriş sayısı aşılmış İzin verilen PIN giriş sayısı aşılmış.
EXCEEDS_WITHDRAWAL_AMOUNT_LIMIT Para çekme limiti/adedi aşılmış Günlük işlem adedi veya limiti aşılmış olabilir.
EXPIRED_CARD Son kullanma tarihi hatalı Kart numarasına ait son kullanma tarihi hatalıdır. Müşteri son kullanma tarihini düzelterek tekrar ödeme deneyebilir.
FRAUD_CHECK_BLOCK Ödeme güvenlik kuralları gereği engellendi Ödeme güvenlik kuralları gereği engellendi.
FRAUD_SUSPECT Ödeme güvenlik denetimini geçemedi Kart bankası ödeme işlemini güvenlik sebebiyle reddetmiştir. Dolandırıcılık şüphesi bulunmakta veya arka arkaya bir çok deneme yapıldığı için hata alınmış olabilir. Ödeme işlemi detayı kontrol edilmeli ve müşteri ile iletişime geçerek ödemenin tekrar denenmesi istenebilir.
INVALID_AMOUNT Geçersiz tutar Geçersiz tutar, işlem tutarını kontrol ediniz. İşlem limiti ve/veya adedi aşılmış olabilir. Detaylı bilgi için banka ile iletişime geçilmelidir.
INVALID_CARD_NUMBER Geçersiz kart numarası Kart numarası banka tarafından kabul edilmedi. Kart numarasının kontrol edilmesi ve ödemenin tekrar denenmesi gerekmektedir.
INVALID_CARD_TYPE Geçersiz kart tipi Geçersiz kart tipi, lütfen kart numarasını kontrol ediniz. Detaylı bilgi için banka ile iletişime geçilmelidir.
INVALID_CAVV Hatalı CAVV bilgisi Kart numarasına ait CAVV hatalıdır. Müşteri, bankası ile iletişime geçmelidir.
INVALID_CHARS_IN_EMAIL E-posta geçerli formata değil Ödeme işlemi sırasında geçerli olmayan bir e-posta kullanılmıştır. E-posta bilgisi kontrol edilmelidir.
INVALID_CVC2_LENGTH CVC uzunluğu geçersiz Kart numarasına ait güvenlik kodu (CVC2) hatalıdır. Müşteri güvenlik kodunu düzelterek tekrar ödeme deneyebilir.
INVALID_CVC2 Cvc2 bilgisi hatalı Ödeme yapılmak istenen kart ile birlikte girilen güvenlik kodu (CVC) uzunluğu geçersizdir. Müşteri güvenlik kodunu düzelterek yeniden ödeme deneyebilir.
INVALID_ECI Hatalı ECI bilgisi Kart numarasına ait ECI hatalıdır. Müşteri, bankası ile iletişime geçmelidir.
INVALID_EXPIRE_YEAR_MONTH Son kullanma tarihi geçersiz Ödeme sırasında girilen son kullanma tarihi geçersizdir. Müşteri girmiş olduğu kart bilgilerini kontrol etmelidir.
INVALID_IP Geçersiz IP Sanal POS'da IP tanımı zorunlu ise lütfen Craftgate IP adreslerini banka ile iletişime geçerek tanımlatınız.
INVALID_MERCHANT_OR_SP Üye işyeri kategori kodu hatalı Kart bankası, üye işyeri kategorisinin hatalı olduğu bilgisini iletmiştir. Banka ile iletişime geçerek üye işyeri kategori düzeltmesi yapılması gerekmektedir.
INVALID_PIN Geçersiz PIN Geçersiz PIN. Müşteri, kart bankası ile iletişime geçmelidir.
INVALID_TRANSACTION Geçersiz işlem. Lütfen başka kart ile deneyiniz Geçersiz işlem. Lütfen ödeme işlemi detayını kontrol ediniz, müşteri detaylı bilgi için kartın bankası ile görüşmelidir.
ISSUER_OR_SWITCH_INOPERATIVE Banka veya terminal işlem yapamıyor Banka veya terminal işlem yapamıyor, anlık bir kesinti yaşanmış olabilir.
LOST_CARD Kayıp kart, karta el koyunuz Kart bankası tarafından kayıp kart bilgisi iletilmektedir. Bu kart ile işlem yapılamaz. Ödeme denemesi dolandırıcılık şüphesi olabilir.
MAY_HAVE_ALREADY_REFUNDED İade edilmek istenen tutar satış tutarından küçük olmalı. Bu ödeme daha önce iade edilmiş olabilir. İade edilmek istenen tutar satış tutarından küçük olmalı. Bu ödeme daha önce iade edilmiş olabilir.
NOT_PERMITTED_TO_CARDHOLDER Kart sahibi bu işlemi yapamaz. Lütfen başka kart ile deneyiniz Kart bankası tarafından bu kart ile ilgili işlem yapılamayacağı bilgisi iletilmiştir. Ödeme farklı bir kart ile denenebilir.
NOT_PERMITTED_TO_FOREIGN_CARD Terminal yurtdışı kartlara kapalı POS'un yurt dışı kartlarla işlem yapmaya yetkisi yok. POS yetkileri kontrol edilmelidir.
NOT_PERMITTED_TO_INSTALLMENT Terminal taksitli işleme kapalı POS'un taksitli işlem yapmaya yetkisi yok, POS yetkileri kontrol edilmelidir.
NOT_PERMITTED_TO_TERMINAL Terminalin bu işlemi yapmaya yetkisi yok POS'un bu işlemi yapmaya yetkisi yok. POS yetkileri kontrol edilmelidir.
NOT_SUFFICIENT_AWARD Yetersiz ödül puanı Ödeme sırasında kullanılmak istenen ödül puanı, kart içinde bulunan puan değerinden yüksektir. Yeterli ödül puanı olmadığı için kullanılmak istenen puan miktarı değiştirilmeli ve tekrar ödeme denemesi yapılmalıdır.
NOT_SUFFICIENT_FUNDS Kart limiti yetersiz, yetersiz bakiye Müşteri kartında ödeme için yeterli bakiye bulunmamaktadır. Müşteri, bankası ile iletişime geçmelidir.
NO_RESPONSE Ödeme işlemi esnasında genel bir hata oluştu Banka beklenen sürede cevap veremedi, bankada anlık bir kesinti yaşanmış olabilir.
NO_SUCH_ISSUER Bankası bulunamadı Kart bankası bulunamadı. Kart numarasının kontrol edilmesi ve ödemenin tekrar denenmesi gerekmektedir.
ORDER_ID_ALREADY_USED Sipariş numarası (orderId) daha önce kullanılmış. Sipariş numaraları başarılı satış bazında tekil olmalıdır. Ödemede kullanılan sipariş numarası (orderId) daha önce başarılı başka bir ödeme sırasında kullanılmıştır. Başarılı geçen ödemeyi kontrol edilmeli, eğer ödeme gerçekleşmediğini düşünüyorsanız yeni bir sipariş numarası ile ödeme tekrar denenmelidir.
PICKUP_CARD Karta el koyunuz Kart bankası güvenlik / dolandırıcılık şüphesi sebebiyle ödemeyi reddetmiştir. Bu kart ile işlem yapılamaz.
POS_BALANCE_NOT_SUFFICIENT Sanal Pos bakiyesi yetersiz Sanal Pos bakiyesi yetersiz.
REFER_TO_CARD_ISSUER Bankanızdan onay alınız Kart bankası ödeme işlemine onay vermemiştir. Müşteri, manuel onay için kart bankasını aramalıdır.
REQUEST_BLOCKED_BY_BANK İstek bankadan hata aldı Ödeme isteği banka tarafından reddedildi.
REQUEST_TIMEOUT Bankaya gönderilen istek zaman aşımına uğradı Banka beklenen sürede cevap veremedi, bankada anlık bir kesinti yaşanmış olabilir.
REQUIRES_DAY_END Gün sonu yapılmalı POS'da gün sonu yapılmadan bu işlem yapılamaz.
RESTRICTED_BY_LAW Kartınız e-ticaret işlemlerine kapalıdır. Bankanızı arayınız. Kart e-ticaret ödemelerine kapalıdır. Müşteri kart bankası ile iletişime geçerek kartını e-ticaret işlemlerine açtırmalıdır.
RESTRICTED_CARD Kısıtlı kart İşlem kısıtlı kart nedeniyle tamamlanamadı. Müşteri, farklı bir kart ile işlemi deneyebilir.
SALES_AMOUNT_LESS_THAN_AWARD Satış tutarı ödül puanından düşük olamaz Ödeme sırasında kullanılmak istenen ödül puanı, ödeme tutarından yüksek olamaz. Kullanılmak istenen ödül tutarı ödeme tutarına eşit veya daha küçük olacak şekilde denenmelidir.
STOLEN_CARD Çalıntı kart, karta el koyunuz Kart bankası tarafından çalıntı kart bilgisi iletilmektedir. Bu kart ile işlem yapılamaz. Ödeme denemesi dolandırıcılık şüphesi olabilir.
THREEDS_INIT_ERROR 3D Secure ödeme başlatılamadı 3D Secure başlatılamadı, detay için banka ile görüşülebilir.
UNKNOWN Ödeme işlemi esnasında genel bir hata oluştu Ödeme başarısız oldu, hata grubu belirlenemedi.