3D Secure (3DS) İşlem API

Bu sayfada, kart sahibinin kimlik doğrulamasıyla güvenli ödeme işlemlerinin gerçekleştirildiği 3D Secure (3DS) API yapısı ve işlem akışı açıklanmaktadır.

🔹3D Secure (3DS) Nedir?

3D Secure (3DS), kartlı ödemelerde kart sahibinin kimliğini doğrulamak ve ödeme güvenliğini artırmak amacıyla geliştirilmiş bir güvenlik protokolüdür.

🔹 3DS İşlem Türleri

3DS doğrulama süreci üç farklı modelde uygulanabilir:

• 3DS MODEL : Doğrulama işlemi tamamlandıktan sonra ödeme işlemi ayrı bir adımda yürütülür. Üye işyeri, doğrulama sonrası Complete3DSPayment servisini çağırarak provizyonu başlatır.

• 3DS PAY: Doğrulama ve ödeme işlemi tek bir akışta tamamlanır. Kart sahibi doğrulamayı geçtikten sonra işlem otomatik olarak provizyona yönlendirilir. Üye işyerinin ayrıca bir çağrı yapmasına gerek kalmaz.

• 3DS HOSTING: Kendi ödeme sayfası olmayan üye işyerleri için VPOS tarafından sağlanan ortak ödeme sayfası kullanılır. Bu modelde, üye işyeri bir ödeme linki oluşturur ve müşteriye iletir.

🔹İşleyiş

Müşteri, bir kartla ödeme yaparken işlem 3D Secure ile korunuyorsa, ek bir doğrulama adımı ile karşılaşır. Bu doğrulama genellikle:

• Tek kullanımlık şifre (OTP – SMS ile)

• Mobil uygulama üzerinden push bildirimi ile onay şeklinde gerçekleşir.

Kart sahibi doğrulamayı başarılı şekilde geçerse, işlem onaylanır. Doğrulama başarısız olursa, işlem otomatik olarak reddedilir.

🔹 Faydaları

• Fraud (Sahtekarlık) Riskini Azaltır: 3DS doğrulama olmadan işlem geçerli sayılmaz.

• Chargeback (İtiraz) Riskini Düşürür: Doğrulama yapılmış işlemler için itiraz olasılığı azalır.

• Operasyonel Maliyetleri Minimuma İndirir: Sahte işlemlerin engellenmesi ile iade ve inceleme maliyetleri düşer.

🔹 Desteklenen 3DS Sürümü

• Bu API, EMV® 3-D Secure 2.2.0 sürümünü desteklemektedir.

• 3DS 2.x sürümleri, kart sahibi deneyimini geliştiren mobil uyumluluk, cihaz bilgisi ve risk bazlı doğrulama gibi özellikleri içerir.

🔹 Geliştirici Notları

• 3DS doğrulama, Non-3DS işlemlerden farklı bir akış gerektirir.

• Ödeme entegrasyonlarında, 3DS doğrulamasını başlatmak için 3DS işlem parametrelerinin doğru gönderilmesi önemlidir.

• Başarılı doğrulama sonrası, işlem provizyon veya satış aşamasına geçebilir.

🔹3DS v2 Akış Diyagramı

🔹3DS v2 İşlem Akış Adımları

🔹3DS İstek Gönderimi

• Üye işyeri, 3DS işlem isteğini HalkÖde sistemine gönderir.

• Bu istek, kart bilgileri ve 3DS parametrelerini içerir.

🔹VPOS Ön Doğrulama ve Akış Belirleme

• VPOS sistemi, kartla ilgili ön kontrolleri gerçekleştirir ve 3DS doğrulama sürecini başlatır.

• Başlatma adımı başarılı olursa, VPOS sistemi üye işyerine base64 formatında HTML içerik dönebilir.

• Üye işyeri bu içeriği çözümler ve kart sahibine gösterir.

Önemli Not: Dönen HTML içeriği her zaman challenge (doğrulama) anlamına gelmez. Frictionless akışta da HTML içerik dönebilir veya hiç dönmeyebilir. Bu durum, VPOS sistemi tarafından değil; issuer bankanın risk değerlendirmesi ve kullanılan 3DS Server altyapısının karar mekanizması doğrultusunda belirlenir.

🔹HTML İçeriğin Kart Sahibine Gösterilmesi

• Üye işyeri, VPOS tarafından base64 formatında iletilen HTML içeriğini çözer.

• Bu içerik, üye işyeri tarafından kart sahibine gösterilir

🔹Kart Sahibi Doğrulaması

• Kart sahibi OTP SMS veya mobil uygulama yöntemi ile kimliğini doğrular.

• Doğrulama tamamlandığında, ACS (Access Control Server) arka planda VPOS sistemine sonucu iletir.

🔹Finansal İşlem Başlatma (Authorization)

• Eğer işlem "requestType": "3DS-PAY" yöntemiyle başlatılmışsa, doğrulama adımından sonra VPOS sistemi otomatik olarak issuer bankaya finansal yetkilendirme (authorization) isteği gönderir. Bu durumda işlem doğrudan provizyona geçer ve ek bir çağrı gerekmez.

• Eğer işlem sadece "requestType": "3DS" parametresiyle başlatılmışsa (yani 3D doğrulama yapılmış ancak ödeme işlemi ayrı yürütülecekse), doğrulama tamamlandıktan sonra üye işyerinin ayrıca Complete3DSPayment isteğini çağırması gerekir. Bu çağrı ile birlikte finansal yetkilendirme (authorization) işlemi başlatılır ve provizyon alınır.

Not: Bu ayrım, entegrasyon sırasında kritik öneme sahiptir. Yanlış yapılandırma durumunda işlem doğrulansa bile ödeme gerçekleşmeyebilir.

🔹Issuer Banka Yanıtı

• Issuer bankadan provizyon yanıtı alınır ve acquirer + VPOS sistemine iletilir.

🔹Return URL ile İşlem Sonucu Bildirimi

• Tüm işlemler tamamlandığında, VPOS sistemi isteğe bağlı olarak tanımlanmış bir Return URL’ye yönlendirme gerçekleştirebilir.

• Bu yönlendirme sayesinde üye işyeri, işlem sonucunu alabilir ve kendi sistemine entegre edebilir. Return URL kullanımı zorunlu değildir; ihtiyaç duyulması halinde yapılandırılabilir.

🔹İşlem Detay Sorgulama

• Üye işyeri, gelen bildirim sonrası VPOS sistemine sorgu göndererek işlem detaylarını alır. (Detaylı bilgi için)

🔹İşlem Detaylarının İletilmesi

• VPOS sistemi, sorgu sonucunda işlem detaylarını üye işyerine iletir.

🔹3DS Akışı Tamamlanması

• Artık 3DS doğrulama ve provizyon süreci tamamlanmıştır.

• Üye işyeri, işlem sonucuna göre gerekli aksiyonları alır:

  • Sonuç mesajını gösterme

  • Satışı tamamlama

  • İade veya iptal gibi ek adımlar

🔹 Return URL Nedir?

Return URL, 3DS işlemi VPOS tarafında tamamlandığında işlem sonucunun üye işyerine bildirildiği URL’dir. Bu mekanizma sayesinde üye işyeri:

• İşlemi kendi sisteminde takip edebilir,

• Kart sahibini bilgilendirebilir,

• Satın alma sürecini yönetebilir.

🔹 İşleyiş

1. 3DS doğrulama ve provizyon süreci VPOS tarafında tamamlandığında, VPOS sistemi return URL’ye yönlendirme yapar.

2. Üye işyeri, bu URL üzerinden HTTP GET endpoint’i sağlar ve bildirimi alır.

3. Bildirim parametreleri Base64 formatında iletilir.

🔹 Base64 Karakter Dönüşümleri

VPOS, URL uyumluluğu için bazı karakterleri dönüştürür:

Orijinal Base64	VPOS Dönüşümü
+	.
/	_
=	-

Bu nedenle üye işyeri, gelen veriyi işlerken:

• . → +

• _ → /

• - → = dönüşümlerini yaparak Base64’i doğru şekilde decode etmelidir.

🔹 Return URL Parametreleri

VPOS, return URL çağrısında aşağıdaki parametreleri gönderir:

• x_nonce → Tek kullanımlık benzersiz değer

• x_timestamp → İşlem zaman damgası

• x_signature → Mesajın bütünlüğünü doğrulamak için imza

• x_body → İşlem token’ını içerir; bu token ile üye işyeri işlem durumunu sorgulayabilir

Not: Endpoint üzerinde veri bütünlüğü kontrolleri mutlaka yapılmalıdır.

🔹 Kullanım Notları

• x_body içindeki işlem token’ı, “Token ile Sorgulama” yöntemi ile işlenebilir.

• Return URL, işlem isteği sırasında tanımlanabileceği gibi, üye işyeri VPOS sisteminde ön tanımlı olarak da ayarlayabilir.

• Bu mekanizma, 3DS akışının tamamlanmasını güvenli ve yönetilebilir hale getirir.

🔹 Webhook / Callback URL Nedir?

Callback URL, VPOS sistemi ile üye işyeri sistemi arasında işlem mutabakatını sağlamak amacıyla kullanılan URL’dir.

🔹 İşleyiş

1. Bir işlem tamamlandıktan birkaç dakika sonra, VPOS sistemi işlem detaylarını üye işyerine gönderir.

2. Üye işyeri, bu bildirim sayesinde:

   • Kendi sistemindeki kayıtları VPOS kayıtları ile karşılaştırabilir,

   • Olası hatalı işlemleri tespit edebilir ve düzeltebilir.

🔹 Kapsadığı Durumlar

• Callback işlemi periyodik olarak çalışır ve 3D ile yapılan tüm işlem türlerini kapsar:

  • 3DS, Link ile Ödeme

  • Satış (Sale), Ön Provizyon (Pre-Sale), İade (Refund), İptal (Void)

• Ayrıca, tüm işlem durumları için bildirim gönderilir:

  • Onaylandı, reddedildi, başarısız, süresi doldu vb.

🔹 Callback URL Parametreleri

VPOS, Callback URL çağrısında aşağıdaki parametreleri gönderir:

• x_nonce → Tek kullanımlık benzersiz değer

• x_timestamp → İşlem zaman damgası

• x_signature → Mesajın bütünlüğünü doğrulamak için imza

• x_body → İşlem detaylarını base64 formatında içerir

Not: Endpoint üzerinde veri bütünlüğü kontrolleri mutlaka yapılmalıdır.

🔹 Kullanım Notları

• x_body içindeki bilgiler, üye işyeri sisteminde işlenerek mutabakat ve kayıt doğrulaması yapılabilir.

• Callback URL, işlem sırasında belirtilebileceği gibi, üye işyeri tanımlama (onboarding) sürecinde de VPOS tarafında ön tanımlı olarak ayarlanabilir.

• Bu mekanizma, özellikle yüksek işlem hacmi olan üye işyerleri için otomatik mutabakat ve hata yönetimini kolaylaştırır.