GarantiPay ile Ödeme Alma (v1)
GarantiPay ile ödeme almak için ilk adım olarak Craftgate'de ödeme başlatılması gerekir. Sonrasında BonusFlaş mobil uygulaması üzerinden ödeme işlemi kullanıcı tarafından tamamlanır. Akabinde ödeme başlatma isteği içerisinde verilmiş olan üye işyeri callback URL adresi ödeme durum bilgisi ile tetiklenir.
GarantiPay Ödeme Başlatma
URL
GarantiPay ile ödeme işlemi için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.
Ödeme Başlatma İsteği Parametreleri
İ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
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 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.
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.
Ödemenin geçmesi gereken posun ismi. Ödemenin geçeceği pos'a kendiniz karar verdiyseniz bu parametre ile ilgili posdan ödeme alabilirsiniz.
Ö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
bkz: GarantiPay Taksit Bilgileri Kullanıcıya sunulacak olan taksit seçenekleri. Gönderilmez ise yalnızca tek çekim işlem gerçekleştirilebilir
Dönüş Parametreleri
Garanti Pay 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 Garanti Pay 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.
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 ödemenin 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
Bankanın veya son kullanıcının GarantiPay 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.
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": "456d1297-908e-4bd6-a13b-4be31a6e47d5",
"paymentId": 1,
"callbackStatus": null,
"conversationData": null
"hash": "3a3f520be02eaca2e689d1db855af3925cbdd8db5f850b2b9e61f7ccb9d997b4"
}
Hash algoritmasına sokulacak değer şu şekilde oluşmalı:
merchantCallbackKeySandbox###SUCCESS###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.
Örnek Kodlar
Açık kaynak kodlu Craftgate API client'larındaki örnek kodları inceleyebilirsiniz.