Örnek Proje ve Gerekli Araçlar
Bu sayfa; örnek entegrasyon projesi, bunu destekleyen Redirect(yönlendirme) projesi, postman collection ve environment dosyalarını içerir.
Gerekli Araçlar ve Linkler
PHP Örnek Proje
SSL sorunu yaşayan kullanıcılar için çözüm olarak, projede yer alan cURL isteklerinde CURLOPT_SSL_VERIFYPEER seçeneğinin değerini false olarak ayarlayabilirsiniz. Bu ayar, cURL kütüphanesinin SSL sertifikalarını doğrulama işlemini devre dışı bırakacaktır.
Postman collection
Postman Collection Environment
Postman Kullanımı ve Temel İşlemler
Postman Nedir ve Neden Kullanıyoruz?
Postman, API'leri test etmek, geliştirmek ve belgelemek için kullanılan popüler bir araçtır. API geliştiricileri için birçok avantaj sunar, özellikle de API'leri hızlı bir şekilde test etmek ve belgelemek amacıyla kullanıyoruz.
Postman Collections İmport Etme
Postman'e Giriş Yapın: Postman uygulamasına giriş yapın veya hesap oluşturun.
Collections Bölümüne Girin: Sol üst köşede bulunan "Collections" sekmesine tıklayın.
Import Collections: Sağ üst köşede bulunan "Import" butonuna tıklayın.
Link veya Dosya Seçin: Collection'ı paylaşılan bir linkten alabilir veya bilgisayarınızdan bir dosya seçebilirsiniz.
Import Edin: Linki veya dosyayı seçtikten sonra "Import" butonuna tıklayarak collection'ı içe aktarın.
Postman Environment İmport Etme
Settings Bölümüne Girin: Sağ üst köşede bulunan dişli simgesine tıklayarak "Settings" bölümüne girin.
Manage Environments: Sol menüde "Manage Environments" seçeneğine tıklayın.
Import Environment: "Import" butonuna tıklayarak, bir önceki adımda indirdiğiniz veya aldığınız environment dosyasını seçin.
Seçtiğiniz Environment'i Aktif Edin: Daha sonra, kullanmak istediğiniz environment'i seçin ve "Set Active" butonuna tıklayarak aktif edin veya ekranın sağ üstünden ilgili environmenti seçin.
Postman Authorization İçin Bearer Token Kullanımı
HST Web Pos API, güvenlik için Bearer Token kullanır. Bu token'ı Postman'da kullanmak için:
Authorization Sekmesine Girin: API isteğinizi açın ve sekme çubuğunda "Authorization" sekmesine gidin.
Type'ı Seçin: "Type" seçeneğini "Bearer Token" olarak ayarlayın.
Token'ı Giriş Yapın: "Token" alanına
{{baseUrl}}şeklinde girin. Bu, environment'da tanımlı olan token'ı kullanmanıza olanak tanır.Kaydedin ve Gönderin: Ayarları kaydedin ve API isteğinizi gönderin.
Login endpointindeki Authorization type "Inherit auth from parent" şeklinde olacaktır.
Diğer endpointlerde ise Authorization type "Bearer Token" şeklinde olmalı. "Token" alanına
{{token}}şeklinde girin. Bu, environment'da tanımlı olan token'ı kullanmanıza olanak tanır.Aşağıda bunlara ait ekran goruntuleri aşağıda mevcuttur.
Postman ile Login isteği Göndermek
Size verilecek olan kullanıcı adı ve şifre ile giriş sağlanacaktır. Şifrenizi sha512 ile şifreleyip göndermeniz gerekmektedir. Aşağıda örnek bir body json kullanım isteği yer almaktadır.
{
"userName": "phonenumberr",
"password": "sha512 ile şifrelenmiş bir şifre",
"lat": "",
"long": ""
}Postman ile Payment isteği Göndermek
Payment isteği atmak için aşağıda örnek bir body json kullanımı mevcuttur.
{
"amount": "1",
"currencyCode": "949",
"orderId": "Guid order id",
"installment": "1",
"cardHolderName": "isim soyisim",
"cardNumber": "kartnumarası",
"expireYear": "2023",
"expireMonth": "01",
"cvc": "555",
"isSecureTransaction": true,
"callbackUrl": "bankadan sonra yonlendirilmesi gereken callback url"
}internal server error hatası alıyorsanız Order id'yi her seferinde farklı bir değer olarak girmelisiniz.
Postman ile Payment Result isteği Göndermek
Payment Result sorgulamak için postmandan istek atarken Query Params olarak paymentId ve orderId gönderilmektedir. Aşağıdaki ekran fotoğrafını örnek bir sorgu mevcuttur.
Örnek vue.js projesi
Entegrasyon süreçlerinde geliştirme süresini kısaltmak amacıyla hazırladığımız örnek bir entegrasyon projesi bulunmaktadır. Bu projeyi vue.js (vue3) teknolojisi kullanarak geliştirdik. Projenin temel amacı, Postman aracılığıyla gerçekleştirdiğimiz işlemlerin, uygulama içindeki implementasyonunu sağlamaktır.
HTTP İstekleri
Axios, web tarayıcıları ve Node.js ortamında çalışan HTTP isteklerini yapmayı kolaylaştıran bir JavaScript kütüphanesidir. Biz de bu projede HTTP isteklerimizi Axios kütüphanesi kullanarak yaptık.
Axios Ayarlarımızı projede bu şekilde tanımladık.
Authstore İle Token Kaydetmek
Kullanıcı, uygulama içindeki işlemler sonucunda bir 'token' elde eder. Bu token, Pinia kütüphanesini kullanarak oluşturduğumuz 'authstore' adlı bir durum deposunda güvenli bir şekilde saklanır. Authstore, kullanıcının oturum durumunu ve ilgili bilgileri depolar. Bu sayede, kullanıcı herhangi bir sayfada gezinirken veya sayfayı yenilerken bile oturumu açık tutabiliriz. Ayrıca, kullanıcının tarayıcıyı kapattıktan sonra bile oturumu sürdürebilmesi için token'ı local storage'da saklarız. Bu yöntem, kullanıcıların güvenli bir şekilde oturum açmalarını ve uygulamayı kullanmalarını sağlayan bir kimlik doğrulama süreci sunar.
Giriş işlemi sonucunda elde ettiğimiz veriyi, AuthState adlı bir durum nesnesi aracılığıyla kullanarak tarayıcımızın local storage bölümüne ilgili 'token'i kaydediyoruz. Bundan sonra gerçekleştireceğimiz tüm işlemlerde, bu 'token'i buradan alacağız. Yani, kullanıcının oturumunu sürdürebilmek ve kimlik doğrulama işlemlerini yapabilmek için elde ettiğimiz bu 'token'i güvenli bir şekilde saklayarak, daha sonraki tüm etkileşimlerde kullanabiliyoruz.
Login Request
Login isteğimizi axios için hazırladığımız ayarların bulunduğu HTTP.ts dosyamız aracılığıyla atıyoruz. Bu dosyamızı login sayfasına import ettikten sonra Kullanıcıdan atacağımız isteğin modellerini doldurmak için basit bir form yapısı hazırladık. Bu forum yapısı credentials modeli içindeki parametreleri dolduracaktır.
Böylece login ve autherize işlemimizi yapıp tokenimizi local storage ' e eklemiş olduk. Sırada diğer istekler var.
Payment Request
Payment Request işlemimizi gerçekleştirmek üzere, bir ödeme isteği servisi oluşturduk. Bu servis, aslında Axios kütüphanesinden türetilmiştir. Axios ayarlarını yapılandırdığımız dosyada, PaymentRequest adında bir method bulunmaktadır. Bu method, Axios kütüphanesini kullanarak ödeme isteği yapıldığı zamanlardaki yapılandırmaları içermektedir. Bu sayede, farklı endpoint'lere gönderilecek olan istekleri birbirinden ayırarak, her birine özgü yapılandırmalar yapma yeteneğine sahip olmamızı sağlıyor.
Burada da Axios konfigürasyon dosyası içinde yazdığımız bir payment Request methodu bulunuyor.
Payment Request ve diğer isteklerin modellerini oluşturmak için Swagger'dan aldığımız JSON dosyasını "swagger-typescript-api" kütüphanesini kullanarak myApi.ts adında tek bir sayfada topladık. Payment Request isteğini oluştururken, ilgili modelimizi bu sayfadan alarak kullanıyoruz.
Bu fotoğrafta göründüğü gibi, her seferinde orderId'in farklı olması için guid olarak tanımlamak amacıyla uuidv4 kütüphanesini kullandık. Web POS sayfasında gösterdiğimiz modeli import edip, ardından kullanıcıdan aldığımız verileri bu modele atarak Payment Request' i gerçekleştirdik.
Gelen response da, return type'a göre tanımlamalarımızı gerçekleştirdik. Eğer Return Type = 2 ise, yanıtta Raw HTML bulunur ve bu HTML, paymentData parametresi içinde yer alır. Return Type = 1 ise, yanıt bir bağlantı (link) olarak gelir ve bu bağlantı, returnUrl parametresi içinde bulunur. Web POS sayfasında örnek bir yanıt JSON'u inceleyebilirsiniz.
Aldığımız tokenı her işlemde değiştirmek için payment request sayfasında yazan yenile butonuna tıklamanız gerekiyor.
Bu aşamadan sonra, bankanın 3D sayfası açılır ve kullanıcı tarafından girilen SMS bilgisi sonrasında, callback URL'e banka sayfasından orderId ve paymentId POST edilir. Vue.js projesinde bu POST işlemini otomatik hale getirmek için, tek bir endpoint'e sahip bir API oluşturduk. Bu API'ye, bankadan gelen veriler post edilir ve Payment Request Result sayfasına query string olarak yönlendirme yapılır. Ödeme Talep Sonuç sayfası, Axios kütüphanesinden türetilen Payment Request Result servisini çalıştırarak, böylece bankadan sonra ödemenin başarılı olup olmadığını otomatik olarak sorgular.
Payment Request isteği gönderirken, bu projede ilgili endpointin URL'sini callbackUrl parametresi içine yerleştirdik ve bu aslında callbackUrl olarak belirlenen adrese bir yönlendirme yapıldı. Bu endpoint ise orderId ve paymentId bilgilerini alarak bu verileri Payment Result Sayfasına iletti.
Manuel olarak Payment Result Request yapabilmek için hazırladığım sayfada Payment Result Request endpointinin nasıl çalıştığını anlatıyor olacağım.
Payment Result Request
Bu sayfada paymentresult endpointine manuel olarak paymentId ve orderId parametreleri girilip istek atılıyor. Gelen sonuca göre de Ödemenin başarılı olup olmadığını kontrol ediyoruz.
Burada da Axios konfigürasyon dosyası içinde yazdığımız bir payment Result Request methodu bulunuyor. Burada da istek gittiğini de notify ile anlamış oluyoruz.
Gelen responsa içinde status == "SUCCESS" ise ödeme başarıyla gerçekleşmiş oluyor ve sayfanın sağ alt tarafında bildirim atıyor. Gelen response içinde "status == 'PENDING'" durumunda ise, bu durum genellikle banka OTP ekranındaki şifrenin girilmesinde oluşan bir sorundan kaynaklanır. Web Pos sayfasında bu response Json modeli örneğini bulabirsiniz.
Last updated