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. Döndürülen hata "yetersiz bakiye" veya "geçersiz işlem" gibi bir iş doğrulama hatasıysa, http kodu 422 döndürülür.

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:

errorCode

string

Hataya ilişkin ayrıştırıcı kod numarası

errorDescription

string

Hatanın niteliğini ifade eden açıklayıcı mesaj

errorGroup

string

(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.

uyarı

Ö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.