GarantiPay ile Ödeme Alma
GarantiPay ödeme akışı, ödemenin gerçekleştiği mobil ve web ortamlarına göre değişiklik göstermektedir. Tüm ödeme akışları GarantiPay Ödeme Başlatma adımında belirtildiği gibi başlatılır. Web üzerinden ilerleyen akışlarda kullanıcı mobil uygulamada ödeme işlemini ilerlettikten sonra ödeme finansallaşarak merchant callback adresine ödeme sonucu dönülür.
Mobil uygulamaya yönlendirilmiş olan APP2APP akışında ise; Ödeme, kullanıcı tarafından
mobil uygulama üzerinde ilerletildikten sonra doğrudan banka tarafından üye işyerinin belirttiği mobileAppReturnUrl adresine yönlendirilir.
Bankanın callback dönüşü sonrası GarantiPay Ödeme Tamamlama servisi çağrılarak ödemenin nihai durumu kontrol edilir.
GarantiPay Ödeme Başlatma
GarantiPay için POS APM Ödeme servisine gelinmesi gerekir. POS APM ödeme başlatma isteğinin içerisinde yer alan
additionalParams ve paymentProvider alanları aşağıdaki gibi doldurulmalıdır.
URL
POS APM ile ödeme işlemi için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.
Ödeme Başlatma İsteği Parametreleri
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.
Ödemenin geçmesi gereken posun ismi. Ödemenin geçeceği pos'a kendiniz karar verdiyseniz bu parametre ile ilgili posdan ödeme alabilirsiniz.
bkz: Para Birimleri Ödemenin tahsil edileceği para birimi
İ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.
Üye işyeri tarafından ödeme isteği içerisinde gönderilen externalId değeri
Bankadan dönen sonucu üye işyerine iletmek için kullanılacak adres
Sadece AUTH desteklenmektedir. bkz: Payment Phases
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.
Ö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
Ö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.
Ö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
Gerekli olan ekstra parametreler burada gönderilmelidir
Kullanıcıya sunulacak olan taksit seçenekleri. Gönderilmez ise posa tanımlı olan komisyon oranları üzerinden taksit seçenekleri kullandırılır
Fraud kontrolü için gönderilebilecek ek parametreler
Dönüş Parametreleri
GarantiPay ile ödeme işleminin sonucunda dönen parametreler API dokümantasyonu giriş sayfasındaki
Dönüş Formatları bölümünde belirtilen kurallara tabidir. Dönen parametreler ödeme akışına göre değişiklik gösterebilmektedir.
Sistemsel ya da kurgusal bir hata bulunmadığı durumda data parametresinde dönen objenin alt parametreleri aşağıdaki gibidir:
Ödemeye ilişkin olarak Craftgate API tarafından türetilen ödeme ID'si
bkz: Ödeme Durumu
Bir sonraki aşamada yapılması gereken adım ile alakalı yönlendirici değerler
Ödeme sonucuna ilişkim ek bilgiler.
Web2App akışında kullanıcının yönlendirilmesi gereken url bilgisi
App2App akışında kullanıcıyı yönlendirmek için kullanılacak değerler
Callback URL'e İletilen Parametreler
Aşağıdaki parametreler form variable olarak HTTP POST metodu kullanılarak iletilir. Doğrulama sonrası Craftgate
tarafından callbackUrl'e yapılacak istekte yer alan parametreler aşağıdaki gibidir:
GarantiPay ödemesinin doğrulamasının durumunu ifade eden değer. Doğrulama başarılıysa SUCCESS, değilse FAILURE değerini alacaktır
Doğrulama başarılı olduğu durumda gönderilir. Ödemeye ilişkin Craftgate API tarafından türetilen ID değeridir
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 başlatma isteğinde gönderilen conversationId parametresinin değeri
Ö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.
Hash Değerinin Oluşurulması
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###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": "d1811bb0-25a2-40c7-ba71-c8b605259611",
"paymentId": 317832,
"callbackStatus": null,
"conversationData": null,
"hash": "919401dcdd7f45bb258759d783e7e88d2ea60144925fb90520ad78e64eb5b427"
}
Hash algoritmasına sokulacak değer şu şekilde oluşmalı:
TjaHHdMbguUSonMEUr4tR42IC0UEtHPb###SUCCESS###317832######d1811bb0-25a2-40c7-ba71-c8b605259611###
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.
Örnek Kodlar
Açık kaynak kodlu Craftgate API client'larındaki örnek kodları inceleyebilirsiniz.
APM ile Ödeme Başlatma
GarantiPay Ödeme Tamamlama
APP2APP ödeme akışında, kullanıcı mobil uygulamadan ödeme sürecini tamamladığında init request parametrelerinde belirtilen mobileAppReturnUrl adresine dönüş sağlanır.
Bu dönüş sonrası complete servisi çağrılarak ödeme tamamlanır.
URL
APM ile ödeme tamamlama işlemi için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.
Ödeme Tamamlama İsteği Parametreleri
POS APM Ödeme başlatma isteğinin cevabında yer alan ödeme ID değeri
Dönüş Parametreleri
POS APM ile ödeme tamamlama 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:
Ö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ı)
Şüpheli işlem olarak belirlenmesi durumunda şüpheli işlem kaydına ait id bilgisi (bkz: Şüpheli İşlem Yönetimi)
Şüpheli işlem olarak belirlenmesi durumunda şüpheli işlem kaydına ait aksiyon bilgisi (bkz: Şüpheli İşlem Aksiyonları)
Ö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.