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:
Hataya ilişkin ayrıştırıcı kod numarası
Hatanın niteliğini ifade eden açıklayıcı mesaj
(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.