3D Secure ile Ödeme Alma
3D Secure ile yapılan ödemeler üç adımda gerçekleşir; başlatma, doğrulama ve tamamlanma. Başlatma isteğinde Craftgate API'sine 3D Secure başarı durumunun iletilebileceği bir callback URL verilirken; bu URL ile tetiklenen üye işyeri iş süreçleri de ödeme ID'sini belirterek ödemeyi tamamlama isteği gönderir ve sürecin uçtan uca tamamlanmasını sağlar.
3D Secure entegrasyonunu yaparken işinize yarayacak güvenlik önerilerine ilgili sayfamızdan ulaşabilirsiniz.
3D Secure Ödeme Başlatma
URL
3D Secure ödeme başlatmak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.
Ödeme Başlatma İsteği Parametreleri
3D Secure ile yapılacak ödemelerde diğer ödemelerden farklı olarak callbackUrl parametresinin gönderilmesi zorunludur. Bu bağlamda 3D Secure ile bir ödeme başlatmak gereken parametreler aşağıdaki gibidir
İstekle beraber gönderilip, cevapla birlikte alınabilecek, "bumerang" değer. Farklı istekleri birbirleriyle ilişkilendirmek için kullanılabilir. Genellikle üye işyerinin ödemeye ilişkin sipariş numarası kullanılır. Sipariş numarası ile kullanmanız sonradan işlemleri incelemenize yardımcı olacaktır.
Veri içinde güvenlik sorunu yaratabilecek özel karakterler kullanılmamalıdır. Veri + veya - karakteri ile başlayamaz, ancak içerisinde kullanılabilir.
Genellikle üye işyeri tarafındaki, ödemeye ilişkin sipariş numarası veya sepet numarası olarak kullanılır. Daha sonradan sorgulama servislerinde bu id ile sorgulama yapabilirsiniz.
Veri içinde güvenlik sorunu yaratabilecek özel karakterler kullanılmamalıdır. Veri + veya - karakteri ile başlayamaz, ancak içerisinde kullanılabilir.
Toplam ödeme tutarı. Sepetteki ürün/hizmet tutarları toplamının bu tutara eşit olması gerekmektedir
Komisyon ve indirim gibi farklar dahil edilerek hesaplanan, karttan çekilecek nihai tutar. Tamamı ya da bir kısmı cüzdandan tahsil edilen ödemelerde cüzdandan tahsil edilecek tutar da bu tutara dahildir. İşlemde vade farkı var ise vade farkı eklenmiş tutar bu parametreye girilmelidir.
buyerMemberId parametresinde belirtilen alıcının cüzdanından tahsil edilecek tutar. Kısmen ya da tamamen cüzdandan tahsil edilecek ödemelerde gönderilmesi zorunludur. Tamamı karttan tahsil edilecek ödemelerde ya da bir buyerMemberId bulunmadığı durumda 0 olarak gönderilebilir.
(Varsayılan: 0)
Ödemenin tahsil edileceği taksit sayısı. Tek çekim için 1 olarak gönderilebilir.
Ödemenin ilişkilendirildiği alıcı ID'si. Üye işyerinin kendi sistemlerindeki ID değerini değil, Craftgate sistemlerindeki ID değerini ifade eder
bkz: Para Birimleri Ödemenin tahsil edileceği para birimi
Genellikle üye işyeri tarafındaki, ödemenin alındığı kanal veya ödemeye özel bir bilgi tutmak için kullanılır. Daha sonradan sorgulama servislerini kullanarak bu değer ile sorgulama yapabilirsiniz.
3D Secure ile yapılan ödemelerde bankadan dönen sonucu üye işyerine iletmek için kullanılacak adres)
Ödeme alınırken bankaya iletilecek orderId parametresi. Opsiyonel olduğu için gönderilmemesi ve orderId değerinin Craftgate tarafından üretilmesi önerilir.
Ödeme yapan alıcının IP adresi.
(bkz. Kart Bilgileri) Tahsilatın gerçekleştirileceği kart bilgileri. Ödeme yöntemine göre ileteceğiniz zorunlu alanlar değişkenlik gösterebilir. Tamamı cüzdandan tahsil edilecek ödemelerde (yani paidPrice'in walletPrice'a eşit olduğu ödemeler) gönderilmemelidir
Ödemeyi geçirmek istediğiniz pos'un alias değeri. Ödemenin geçeceği pos'a kendiniz karar verdiyseniz bu parametre ile ilgili posdan ödeme alabilirsiniz.
Bazı ödeme hatalarından(invalid transaction, do not honour vs) sonra otomatik olarak ikinci bir pos ile denenip denenmeyeceğine karar verebilirsiniz.
Ödemeye ilişkin kırılım bilgileri. En az bir kırılım gönderilmesi ve gönderilen kırılımların tutarlarının toplamının price alanına eşit olması zorunludur
Ödemeye ait gönderilmek istenen ek parametreler. bkz: Ödeme Ek Parametreleri
Dönüş Parametreleri
3D Secure ile ödeme işleminin sonucunda dönen parametreler API dokümantasyonu giriş sayfasındaki Dönüş Formatları bölümünde belirtilen kurallara tabidir. Sistemsel ya da kurgusal bir hata bulunmadığı durumda data parametresinde dönen objenin alt parametreleri aşağıdaki gibidir:
Kullanıcıya gösterilecek 3D Secure formunun HTML kod içeriği. Bu değer Base64-encoded olarak gönderilmekte olup, gösterimden önce üye işyeri tarafindan Base64 decode edilmelidir
Ödemenin id bilgisi.
3D Secure Doğrulama V1
Üye işyeri tarafından gönderilen ödeme başlatma isteği ile başlayan 3D Secure ödeme süreci, kullanıcı doğrulaması ile devam eder. Bunun için başlatma isteğine dönülen cevaptaki HTML içeriğinin decode edilerek kullanıcıya gösterilmesi gerekmektedir.
Kullanıcı kendisine iletilen doğrulama kodu girdikten sonra doğrulama sonucu ilgili banka tarafından Craftgate API'sine iletilir. Craftgate API, aldığı sonucu ödemeyle ilgili birtakım bilgilerle birlikte harmanlayarak, ödeme başlatma isteğinde üye işyeri tarafından gönderilmiş olan callbackUrl adresine bir istek yaparak iletir.
Callback URL'e İletilen Parametreler
Aşağıdaki parametreler form variable olarak HTTP POST metodu kullanılarak iletilir. Üye işyerinin callback adresine kullanıcı tarayıcısından ulaşılacağı için, bu adres internete açık olmalı ve application/x-www-form-urlencoded content-type'ını karşılayabilmelidir.
Doğrulama sonrası Craftgate tarafından callbackUrl'e yapılacak istekte yer alan parametreler aşağıdaki gibidir:
3D Secure doğrulamasının durumunu ifade eden değer. Doğrulama başarılıysa SUCCESS, değilse FAILURE değerini alacaktır
Ödeme başlatma isteğinde gönderilen conversationId parametresinin değeri
Doğrulama başarılı olduğu durumda gönderilir. Ödemeye ilişkin Craftgate API tarafından türetilen ID değeridir
Bazı banka ve ödeme kuruluşlarının 3D Secure modeline göre doğrulama ve tamamlama işlemi aynı anda olabilmektedir. Bu değer WAITING ise 3D Secure tamamlama servisini çağırmalısınız, COMPLETED ise ödeme tamamlanmıştır, buna göre sisteminizi güncellemeniz gerekmektedir.
Bankanın veya son kullanıcının 3DS doğrulama adımını tekrar tetiklemesi durumunda, ödeme daha önceden doğrulanmış ise gönderilir. Status alanı FAILURE değerini alırken, callbackStatus değeri ALREADY_RETURNED olarak gönderilecektir. Bu alan ALREADY_RETURNED değeriyle geldiği durumda, sisteminizde ödemenin durumu kontrol edilmeli ve tamamlanmışsa bir aksiyon alınmamalıdır.
Başarılı responselarda dönülen güvenli iletişim datasıdır. Bu parametrenin döndüğü durumda doğrulamanın sağlanması amacıyla complete aşamasında gönderilmeli.
Ödeme sonucu dönülen parametrelerin Sha-256 Hex algoritması ile şifrelenmesi sonucu oluşan değerdir. Detaylı açıklama aşağıda, "Hash Değerinin Oluşurulması" başlığında mevcuttur.
3DS Doğrulama V1 için Mecburi Güvenlik Adımı: Hash Değerinin Oluşurulması ve Kontrolü
Üye işyerinin Callback URL'ine, Craftgate'in geldiği gibi kötü niyetli kişiler de istek atabilir. O nedenle CALLBACK URL'E GELEN HİÇBİR İSTEĞE, HASH KONTROLÜ YAPMADAN KESİNLİKLE GÜVENMEYİNİZ.
Response içerisinde bulunan hash değeri, dönülen parametrelerin doğrulamasını sağlamak amacıyla Sha-256 Hex algoritması ile hashlenerek oluşturulur.
- İşlem için gerekli 32 Haneli key değerine şuradan ulaşılabilir: Panel üzerinde bulunan Yönetim -> Üye İşyeri Ayarları arayüzündeki "Üye İşyeri Callback Key"
- Hash algoritmasına sokulacak değer aşağıdaki sırayla her parametrenin arasına delimiter olarak "###" eklenerek oluşturulmalıdır
- null değerlerin yerine empty string ("") yazılmalıdır.
{threedSecureCallbackKey}###{status}###{completeStatus}###{paymentId}###{conversationData}###{conversationId}###{callbackStatus}
Örnek olarak aşağıdaki response'u hash algoritmasına sokalım ve Üye İşyeri Callback Key değerinin "merchantCallbackKeySandbox" olduğunu varsayalım.
{
"status": "SUCCESS",
"conversationId": "456d1297-908e-4bd6-a13b-4be31a6e47d5",
"paymentId": 1,
"completeStatus": "COMPLETED",
"callbackStatus": null,
"conversationData": null
"hash": "fffe880629292588380ae03732e2e69d223f07a099c908ec8664e3b033c7523a"
}
Hash algoritmasına sokulacak değer şu şekilde oluşmalı:
merchantCallbackKeySandbox###SUCCESS###COMPLETED###1######456d1297-908e-4bd6-a13b-4be31a6e47d5###
Oluşturulan değerin "Üye İşyeri Callback Key" ile Sha-256 Hex algoritamsına sokularak hashlenmesi ile response'da bulunan "hash" parametresinin eşitliği karşılaştılarak validasyon sağlanabilir.
3D Secure Doğrulama v2 (Önerilen)
3D Secure Doğrulama v2 yapısı ile callback aşamasında mdStatus değerine erişebilirsiniz. İleride callback isteği içerisine farklı alanlarında eklenebileceğini göz önünde bulundurarak hash hesaplaması dinamik olacak şekilde yapılmalıdır. Hash hesaplamasına ait detaylar aşağıda yer almaktadır.
3D Secure Doğrulama v2 yapısını kullanabilmeniz için 3D Secure Ödeme Başlatma isteği içerisinde yer alan additionalParams parametresi altında threeDSCallbackVersion değerini 2 olarak göndermeniz gerekmektedir.
Callback URL'e İletilen Parametreler
Aşağıdaki parametreler form variable olarak HTTP POST metodu kullanılarak iletilir. Üye işyerinin callback adresine kullanıcı tarayıcısından ulaşılacağı için, bu adres internete açık olmalı ve application/x-www-form-urlencoded content-type'ını karşılayabilmelidir.
Doğrulama sonrası Craftgate tarafından callbackUrl'e yapılacak istekte yer alan parametreler aşağıdaki gibidir:
3D Secure doğrulamasının durumunu ifade eden değer. Doğrulama başarılıysa SUCCESS, değilse FAILURE değerini alacaktır
Ödeme başlatma isteğinde gönderilen conversationId parametresinin değeri
Doğrulama başarılı olduğu durumda gönderilir. Ödemeye ilişkin Craftgate API tarafından türetilen ID değeridir
Bazı banka ve ödeme kuruluşlarının 3D Secure modeline göre doğrulama ve tamamlama işlemi aynı anda olabilmektedir. Bu değer WAITING ise 3D Secure tamamlama servisini çağırmalısınız, COMPLETED ise ödeme tamamlanmıştır, buna göre sisteminizi güncellemeniz gerekmektedir.
Bankanın veya son kullanıcının 3DS doğrulama adımını tekrar tetiklemesi durumunda, ödeme daha önceden doğrulanmış ise gönderilir. Status alanı FAILURE değerini alırken, callbackStatus değeri ALREADY_RETURNED olarak gönderilecektir. Bu alan ALREADY_RETURNED değeriyle geldiği durumda, sisteminizde ödemenin durumu kontrol edilmeli ve tamamlanmışsa bir aksiyon alınmamalıdır.
Başarılı responselarda dönülen güvenli iletişim datasıdır. Bu parametrenin döndüğü durumda doğrulamanın sağlanması amacıyla complete aşamasında gönderilmeli.
3D Secure doğrulamasının sonucunu ifade eden değer.
Hash hesaplamasında kullanılan parametrelerin sıralı olarak gönderildiği alandır. : karakterine göre parametreler ayrıştırılarak, ilgili parametre değerleri ard arda eklenerek hash hesaplamasına dahil edilmelidir.
Üye İşyeri Callback Key değerinin, hashParams alanında açıklandığı şekilde ilgili değerlerin oluşturularak birleştirilip Sha-256 Hex algoritması ile şifrelenmesi sonucu oluşan değerdir. Hash değerinin oluşturması için örnek kodlar aşağıda yer almaktadır.
3DS Doğrulama V2 için Mecburi Güvenlik Adımı: Hash Değerinin Oluşurulması ve Kontrolü
Üye işyerinin Callback URL'ine, Craftgate'in geldiği gibi kötü niyetli kişiler de istek atabilir. O nedenle CALLBACK URL'E GELEN HİÇBİR İSTEĞE, HASH KONTROLÜ YAPMADAN KESİNLİKLE GÜVENMEYİNİZ.
İşlem için gerekli 32 Haneli key değerine Panel üzerinde bulunan Yönetim -> Üye İşyeri Ayarları arayüzündeki "Üye İşyeri Callback Key" alanından ulaşabilirsiniz.
- Java
- Node.js
public boolean verifyHash(Map<String, String> callbackParams, String callbackKey) {
String hashValues = Arrays.stream(callbackParams.get("hashParams").split(":"))
.map(callbackParams::get)
.collect(Collectors.joining());
String calculatedHash = DigestUtils.sha256Hex(callbackKey + hashValues);
return calculatedHash.equals(callbackParams.get("hash"));
}
function verifyHash(callbackParams, callbackKey) {
const hashValues = callbackParams['hashParams'].split(':')
.map(param => callbackParams[param])
.join('');
const calculatedHash = crypto
.createHash('sha256')
.update(callbackKey + hashValues)
.digest('hex');
return calculatedHash === callbackParams['hash'];
}
Örnek olarak aşağıdaki callback içeriğinin iletildiğini ve Üye İşyeri Callback Key değerinin merchantCallbackKeySandbox olduğunu varsayalım.
status=SUCCESS
callbackStatus=
completeStatus=WAITING
paymentId=863
conversationData=
conversationId=d1811bb0-25a2-40c7-ba71-c8b605259611
mdStatus=1
hashParams=status:callbackStatus:completeStatus:paymentId:conversationData:conversationId:mdStatus
hash=07089c50db7babb19a7af7aba11d4acbe43f971355dbbde77de4fcc7d9cd56cc
hashParams parametrelerinden null değerleri eleyip String olarak birleştirmelisiniz. 3D Secure Doğrulama v1'den farklı olarak bu adımında hashString içerisine ### karakteri koyulmamaktadır.
Örnekte, hash algoritmasına sokulacak değer şu şekilde oluşmalı:
merchantCallbackKeySandboxSUCCESSWAITING863d1811bb0-25a2-40c7-ba71-c8b6052596111
Yukarıdaki algoritma kullanılarak oluşacak hash değeri aşağıdaki gibi olacaktır.
07089c50db7babb19a7af7aba11d4acbe43f971355dbbde77de4fcc7d9cd56cc
Oluşturulan değerin istek içerisinde bulunan "hash" parametresine eşitliği karşılaştılarak validasyon sağlanmalıdır.
3D Secure Ödeme Tamamlama
Doğrulaması başarıyla gerçekleşen ödemelerde, sonucun Craftgate tarafından callbackUrl'e yapılacak istekle üye işyerine iletilmesinin ardından, üye işyerinin Craftgate API'ye bir tamamlama isteği gönderek süreci tamamlaması gerekmektedir. Bu istek yapılmadığı sürece tahsilat gerçekleşmeyecektir. Tamamlanma isteği yapılmadığı ya da doğrulama sonrası Craftgate tarafından callbackUrl'e erişilemediği için askıda kalacak ve üye işyeri panelinde sarı renkle gösterilecektir.
URL
3D Secure ödeme tamamlamak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.
Ödeme Tamamlama İsteği Parametreleri
Doğrulama adımından başarıyla geçen ödemeler için yapılacak tamamlama isteğinin parametreleri aşağıdaki gibidir:
Ödemeye ilişkin olarak Craftgate API tarafından türetilen ve callbackUrl'e iletilen ödeme ID'si
Ödeme Tamamlama Dönüş Parametreleri
3D Secure ile yapılan ödemelerin tamamlama isteklerine verilen cevap, standart bir ödeme ile eşdeğer olup, ödemeye ilişkin detayları içerir. Bu cevabın formatı ve içerdiği parametreler için bkz. Ödeme Alma - Dönüş Parametreleri
Ödemenin ID'si. Bu değer ödeme isteği için Craftgate tarafından belirlenen eşsiz değerdir. Veritabanınızda sipariş bilgileri ile eşleştirip saklamayı unutmayınız.
Ödemenin gerçekleştirildiği tarih
Ödemenin toplam sepet tutarı
Müşterinin ödediği toplam tahsilat tutarı. Tamamı ya da bir kısmı cüzdandan tahsil edilen ödemelerde cüzdandan tahsil edilecek tutar da bu tutara dahildir
Cüzdandan tahsil edilen tutar
Ödemeye ilişkin para birimi. bkz: Para Birimleri
Alıcı üyeyle ilişkilendirilmiş ödemelerde yer alan, ilgili üyenin ID'sini belirten değer
Ödemenin taksit sayısı
Üye işyeri tarafından ödeme isteği içerisinde gönderilen conversationId değeri
Üye işyeri tarafından ödeme isteği içerisinde gönderilen externalId değeri
bkz: Ödeme Tipleri
bkz: Ödeme Durumu
Üye işyeri tarafından ödeme isteği içerisinde gönderilen paymentChannel değeri
Ödemenin 3D Secure ile gerçekleştirilip gerçekleştirilmediği
Son kullanıcıya yansıtılan vade farkı oranı
Son kullanıcıya yansıtılan vade farkı tutarı. paidPrice ile price arasındaki farka eşittir
Banka komisyon oranı
Banka komisyon tutarı
Ödeme esnasında kart saklanmak istenmiş ise kart saklanır ve bu alan dolu gelir. Başarılı ödeme sonrası kaydedilen kartın saklı kart kullanıcı anahtarını ifade eder. Üye işyeri tarafından müşteriyle ilişkilendirilerek saklanmalıdır
Ödeme esnasında kart saklanmak istenmiş ise kart saklanır ve bu alan dolu gelir. Başarılı ödeme sonrası kaydedilen kartın saklı kart anahtarını ifade eder. Üye işyeri tarafından müşteriyle ilişkilendirilerek saklanmalıdır
Ödemenin saklı kartla gerçekleştirilip gerçekleştirilmediğini belirtir
Kartın ilk 8 hanesini belirtir. Tamamı cüzdan ile ödenen ödemelerde boş gelir.
Kartın son 4 hanesini belirtir. Tamamı cüzdan ile ödenen ödemelerde boş gelir
Kart sahibinin adı/soyadı
Bankada kayıtlı olan kart sahibi adı/soyadı. Bazı durumlarda PF poslarında dönüş null olabilir
Ödemeye ilişkin banka tarafından verilen authCode değeri. Tamamı cüzdan ile ödenen ödemelerde boş gelir. Bazı durumlarda PF poslarında dönüş null olabilir
Ödemeye ilişkin banka tarafından verilen hostReference değeri. Tamamı cüzdan ile ödenen ödemelerde boş gelir
Ödemeye ilişkin banka tarafından verilen transId değeri. Tamamı cüzdan ile ödenen ödemelerde boş gelir. Bazı durumlarda PF poslarında dönüş null olabilir
Ödemeye ilişkin banka tarafından verilen orderId değeri
(bkz: Kart Tipleri) Kartın tipini ifade eder. Tamamı cüzdan ile ödenen ödemelerde boş gelir
Kartı sağlayan kart kuruluşuunu ifade eder. Tamamı cüzdan ile ödenen ödemelerde boş gelir
Ödemenin alındığı kartın ailesini belirtir. Tamamı cüzdan ile ödenen ödemelerde boş gelir
Üye işyeri tarafından ödeme isteği içerisinde gönderilen posAlias değeri
Ödemenin alındığı pos bilgileri
Ödemede kullanılmış olan ödül bilgileri (bkz: Ödül ve Puan Kullanımı)
Ödeme isteği yapılırken gönderilen kırılım bilgileri ile, ödemenin bu kırılımlar bazındaki fiyatlama ve para gönderimi bilgilerini içerir
Ödeme sonucuna ilişkim ek bilgiler.
Örnek Kodlar
Açık kaynak kodlu Craftgate API client'larındaki örnek kodları inceleyebilirsiniz.