Web Pos (3D Ödeme)
Base url : https://virtualapitest.hstmobil.com.tr
3D Ödeme Servisi İstek Modeli;
POST /api/Payments/Payment HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 208
{
"amount": 1,
"currencyCode": 1,
"orderId": "text",
"installment": 1,
"cardHolderName": "text",
"cardNumber": "text",
"expireYear": "text",
"expireMonth": "text",
"cvc": "text",
"isSecureTransaction": true,
"callbackUrl": "text"
}Success
No content
3D Ödeme Servisi İşlem Akışı;
3D ödeme modelini kullanarak başarılı bir tahsilat gerçekleştirmek için aşağıda maddeler halinde açıklanan işlemleri takip ederek entegrasyonunuzu tamamlamanız gerekmektedir.
1. Adım:
Üye işyeri kullanıcı, kart, sepet, ödeme tutar ve taksit bilgilerini, ödemenin sonucunun bildirilmesini istediği kendi web adresi(BACK_URL) bilgisi ile birlikte 3D ödeme servisine yukarıda belirtilmiş olan istek modelini kullanarak ödeme isteğini gönderir ve ödeme işlemini başlatmış olur.
Güvenli ve sorunsuz bir şekilde işlemlerin gerçekleşebilmesi ve fraud işlemlerin önlenebilmesi için tüm parametrelerin eksiksiz bir şekilde gönderilmesi gerekmektedir.
Servise gönderilmesi gereken parametreler şu şekildedir;
3D Ödeme Servisi İstek Mesajı Parametreleri
amount
String
Evet
Ödeme işlemine ait işlem tutarı bilgisidir.
currencyCode
int
Evet
Ödeme işleminin gerçekleştirileceği para birimi bilgisidir. Şu an için sadece "949" gönderilebilir. (Türk lirasi)
orderId
String
evet
Üye iş yeri tarafından verilecek order id bilgisidir. Ödeme işlemleri bu referans numarası ile takip edilebilir. String GUID karakter kullanılabilir.
cardHolderName
String
Evet
Ödeme işleminin gerçekleştirileceği kart sahibinin ad ve soyadı bilgisidir.
cardNumber
String (16 hane)
Evet
Ödeme işleminin gerçekleştirileceği karta ait 16 haneli kart numarası bilgisidir.
expireYear
DateTime
(String (4 haneli))
Evet
Ödeme işleminin gerçekleştirileceği karta ait 4 haneli son kullanım tarihini yıl bilgisidir.
expireMonth
String
Evet
Ödeme işleminin gerçekleştirileceği karta ait 2 haneli son kullanım tarihini ay bilgisidir.
cvc
String
Evet
Ödeme işleminin gerçekleştirileceği kartın arka yüzünde bulunan 3 haneli güvenlik kodu bilgisidir.
isSecureTransaction
Bool
Evet
3D ödeme
callbackUrl
String
Evet
İşlem sonuç cevabının sistem tarafından döndürüleceği adres bilgisidir. İşlem cevabı üye iş yeri tarafından bu adresten okunacaktır. İşlem sonucu form post olarak gönderilir.
Installment
int
Evet
Ödeme işlemi için istenen taksit sayısı bilgisidir. Tek çekim işlemler için “1” bilgisi gönderilmelidir.
Servise gönderilecek isteğin modeli örnek projede şu şekildedir;
Servise gönderilecek örnek bir JSON dosyası şu şekildedir;
{
"amount": "10",
"currencyCode": "949",
"orderId": "ASFASF87687678690988" ,
"installment": 5 ,
"cardHolderName": "İsim Soyisim" ,
"cardNumber": "4589963225894785" ,
"expireYear": "2023",
"expireMonth": "12" ,
"cvc": "000" ,
"isSecureTransaction": true ,
"callbackUrl": "İşlem sonucunun üye iş yerine döndürüleceği url adresi" ,
}orderId değeri her işlemde değişmeli ve string olarak benzersiz (GUID) şeklinde gönderilmelidir.
OrderId Formatı bu şekilde olmalıdır : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
(- işareti kaldırılarak gönderilmelidir).
Payment request response kısmında 500 internal server error dönüyorsa bunu sebebi aynı order Id girildiğinden olabilir. Her farklı payment request için farklı orderId girilmek zorundadır.
2. Adım
Hstmobil bilgileri değerlendirerek üye iş yerine cevap mesajını gönderir.(Cevap mesajı içerisinde ReturnType alanı bulunur.) ReturnType ' a göre kullanıcıya;
Eğer 'ReturnType: 1' olarak belirtilmişse, size bir URL dönecektir. Bu URL 3D Doğrulama Sayfasına yönlendirecektir.
Eğer 'ReturnType: 2' olarak belirtilmişse, size bir HTML sayfası verisi dönecektir. Banka tarafından dönen 3d doğrulama iframe'dir. (Raw HTML türünde)
Servisten işlem sonrasında gönderilen cevap mesajına ait parametreler şu şekildedir;
3D Ödeme Servisi Cevap Mesajı Parametreleri
orderId
String
Evet
Üye iş yeri tarafından verilecek order id bilgisidir. Ödeme işlemleri bu referans numarası ile takip edilebilir. Maksimum 24 karakter kullanılabilir.
returnUrl
int
ReturnType türüne göre
Üye iş yerinin kullanıcıyı yönlendireceği 3D Doğrulama Sayfası URL Adresi
errorCode
String
evet
Başarısız ödeme işlemi sonucu hata kod bilgisidir. Banka hata kodları da bu parametre içerisinde dönüş yapılır.
paymentId
String
evet
Ödeme işlemine ait HstMobil sistemi tarafından verilen paymentId bilgisi
paymentData
Raw HTML veya Link
ReturnTürüne göre
Banka tarafından dönen 3d doğrulama iframe'dir.
returnType
int
evet ; 1 veya 2 gelebilir
Ödeme işleminin hangi tür ile yapılacağının durum kod bilgisidir. 1 gelirse url ile ödeme 2 gelirse 3d doğrulama iframe'dir.(RAW HTML)
success
boolean
evet
Ödeme sonucu
message
String
" "
Ödeme sonuç mesajı
resultCode
String
" "
Ödeme sonuç kodu
Servisten gelen örnek bir response JSON dosyası şu şekildedir;
{
"data": {
"responseMessage": "(TR) - işlem başarılı - 43061",
"orderId": "5555eeee67776666888555",
"returnUrl": null,
"errorCode": null ,
"status": "SUCCESS" ,
"paymentId": "5555eeee67776666888555" ,
"paymentData": "OTP SMS EKRANI(HTML VERİ)",
"returnType": "1 veya 2 gelebilir",
},
"success": "true" ,
"message": "null" ,
"resultCode": "0000" ,
}Bankaların ödeme ekranına yönlendirme işlemleri için iki farklı yöntem bulunmaktadır. Bu yöntemlerden biri kullanıldığında diğer yöntemin değeri "null" olarak kabul edilir. İki durumu şu şekilde açıklayabiliriz:
Eğer returnType değişkeni 1 ise, "returnUrl" değeri bankanın ödeme ekranına yönlendiren bir link oluşturacaktır. Bu durumda PaymentData değişkeni, banka ekranına link ile yönlendirme sağlandığı için "null" olarak dönecektir.
Diğer durumda, yani returnType değişkeni 2 olduğunda, paymentData değişkeni içinde bir banka HTML iFrame değeri bulunacaktır. Bu durumda ise returnUrl değişkeni "null" olarak kabul edilir.
Link veya HTML iFrame değerini kullanabilmek için iki farklı konfigürasyon yapmanız gerekmektedir.
Ödeme İşlemi Sonlandırma
POST /api/Payments/PaymentResult HTTP/1.1
Host:
Authorization: YOUR_API_KEY
Accept: */*
Success
No content
Ödeme işlemi tamamlandığında, "callbackUrl" sayfasına iletilen veri içindeki orderId ve paymentId parametrelerini göndermek önemlidir. Bu iki parametreyi "callbackUrl" sayfasına POST etmelisiniz.
{
"data":
{
"paymentId": null,
"orderId": "1ae8af2024c811ee8844dd9840dd82ae",
"amount": 60,
"firstInquiryTime": "0001-01-01T00:00:00",
"inquiryAlreadyCalled": false,
"operationDate": null,
"status": "SUCCESS",
"code": null,
"message": "SUCCESS",
"operation": null,
"transactionOrderId": "1ae8af2024c811ee8844dd9840dd82ae"
},
"errorInfo": null,
"messages": null,
"succeeded": false
}Payment isteği yaparken girdiğiniz callback url'e banka otp ekranından sonra yönlendirme yapılırken form verisi gönderilir. Buradaki OrderId ve PaymentId parametrelerini "callbackUrl" sayfasına POST etmelisiniz.
Taksit Oranı Sorgulama
Bu endpoint, kullanıcıların geçerli olan taksit komisyon oranlarını sorgulamasını sağlar. Kullanıcılar, belirtilen URL'ye POST isteği göndererek mevcut taksit oranlarını ve diğer ilgili bilgileri JSON formatında alabilirler.
Bu enpointe istek atmak için login olunması gerekmektedir.
Bu endpoint'e istek gönderirken body kısmı boş bırakılmalıdır.
Aşağıda, cURL komutunu kullanarak bu endpoint'e nasıl istek göndereceğinizi gösteren bir örnek verilmiştir:
curl -X 'POST' \
'https://virtualapi.hstmobil.com.tr/api/Payments/Get-All-Installment' \
-H 'accept: */*' \
-H 'Authorization: Bearer <Aldığınız Acces Token>' \
-d ''Last updated