3D Secure ile Ödeme Alma

3D Secure ile yapılan ödemeler üç adımda gerçekleşir: başlatma, doğrulama ve tamamlanma. Başlatma isteğinde ÖderoPay API'sine 3D Secure başarı durumunun iletilebileceği bir callback URL verilirken; bu URL ile tetiklenen üye işyeri iş süreçleri de ödeme ID'sini belirterek ödemeyi tamamlama isteği gönderir ve sürecin uçtan uca tamamlanmasını sağlar.

3D Secure Ödeme Başlatma

URL

3D Secure ödeme başlatmak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.

HTTP Metod URL
POST /payment/v1/card-payments/3ds-init

Ödeme Başlatma İsteği Parametreleri

3D Secure ile yapılacak ödemelerde diğer ödemelerden farklı olarak callbackUrl parametresinin gönderilmesi zorunludur. Bu bağlamda 3D Secure ile bir ödeme başlatmak gereken parametreler aşağıdaki gibidir

Parametre Adı Tipi Zorunlu Açıklama
conversationId string Hayır İ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
price decimal Evet Toplam ödeme tutarı. Sepetteki ürün/hizmet tutarları toplamının bu tutara eşit olması gerekmektedir
paidPrice decimal Evet Komisyon ve indirim gibi farklar dahil edilerek hesaplanan, müşterinin ödeyeceği toplam tahsilat tutarı. Tamamı ya da bir kısmı cüzdandan tahsil edilen ödemelerde cüzdandan tahsil edilecek tutar da bu tutara dahildir
walletPrice decimal Hayır buyerId parametresinde belirtilen alıcının cüzdanından tahsil edilecek tutar. Kısmen ya da tamamen cüzdandan tahsil edilecek ödemelerde gönderilmesi zorunludur. Tamamı karttan tahsil edilecek ödemelerde ya da bir buyerId bulunmadığı durumda 0 olarak gönderilebilir. (Varsayılan: 0)
installment integer Evet Ödemenin tahsil edileceği taksit sayısı. Tek çekim için 1 olarak gönderilebilir. Alabileceği degerler 1, 2, 3, 6, 9 ve 12'dir
buyerId long Hayır Ödemenin ilişkilendirildiği alıcı ID'si. Üye işyerinin kendi sistemlerindeki ID değerini değil, ÖderoPay sistemlerindeki ID değerini ifade eder
currency Currency Evet bkz: Para Birimleri Ödemenin tahsil edileceği para birimi
paymentGroup PaymentGroup Evet bkz: Ödeme Grupları
callbackUrl string Evet* 3D Secure ile yapılan ödemelerde bankadan dönen sonucu üye işyerine iletmek için kullanılacak adres (bkz. 3D Secure ile Ödeme Alma)
card Card Hayır (bkz. Kart Bilgileri) Tahsilatın gerçekleştirileceği kart bilgileri. Tamamı cüzdandan tahsil edilecek ödemelerde (yani paidPrice'in walletPrice'a eşit olduğu ödemeler) gönderilmesi zorunlu değildir
posAlias string Hayır TOKENGATE ödemeleri için kullanılır, doldurulması durumunda ödeme bu pos kullanılarak yapılacaktır. bkz. Gateway Ödemeleri
items PaymentItem[] Evet (bkz. Ödeme Kırılım Bilgileri) Ö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

*: Normal şartlarda zorunlu olmayan bu alan, 3D Secure ödemelerinde zorunlu olduğu için vurgulanmıştır

Dönüş Parametreleri

3D Secure 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:

Parametre Adı Tipi Her Zaman Mevcut Açıklama
htmlContent string Evet Kullanıcıya gösterilecek 3D Secure 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

3D Secure Doğrulama

Üye işyeri tarafından gönderilen ödeme başlatma isteği ile başlayan 3D Secure ödeme süreci, kullanıcı doğrulaması ile devam eder. Bunun için başlatma isteğine dönülen cevaptaki HTML içeriğinin decode edilerek kullanıcıya gösterilmesi gerekmektedir.

Kullanıcı kendisine iletilen doğrulama kodu girdikten sonra doğrulama sonucu ilgili banka tarafından ÖderoPay API'sine iletilir. ÖderoPay API, aldığı sonucu ödemeyle ilgili birtakım bilgilerle birlikte harmanlayarak, ödeme başlatma isteğinde üye işyeri tarafından gönderilmiş olan callbackUrl adresine bir istek yaparak iletir.

Callback URL'e İletilen Parametreler

Aşağıdaki parametreler form variable olarak HTTP POST metodu kullanılarak iletilir. Doğrulama sonrası ÖderoPay tarafından callbackUrl'e yapılacak istekte yer alan parametreler aşağıdaki gibidir:

Parametre Adı Tipi Her Zaman Mevcut Açıklama
status string Evet 3D Secure doğrulamasının durumunu ifade eden değer. Doğrulama başarılıysa SUCCESS, değilse FAILURE değerini alacaktır
conversationId string Hayır Ödeme başlatma isteğinde gönderilen conversationId parametresinin değeri
paymentId long Hayır Doğrulama başarılı olduğu durumda gönderilir. Ödemeye ilişkin ÖderoPay API tarafından türetilen ID değeridir

3D Secure Ödeme Tamamlama

Doğrulaması başarıyla gerçekleşen ödemelerde, sonucun ÖderoPay tarafından callbackUrl'e yapılacak istekle üye işyerine iletilmesinin ardından, üye işyerinin ÖderoPay API'ye bir tamamlama isteği gönderek süreci tamamlaması gerekmektedir. Bu istek yapılmadığı sürece tahsilat gerçekleşmeyecektir. Tamamlanma isteği yapılmadığı ya da doğrulama sonrası ÖderoPay tarafından callbackUrl'e erişilemediği için askıda kalacak ve üye işyeri panelinde sarı renkle gösterilecektir.

URL

3D Secure ödeme tamamlamak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.

HTTP Metod URL
POST /payment/v1/card-payments/3ds-complete

Ödeme Tamamlama İsteği Parametreleri

Doğrulama adımından başarıyla geçen ödemeler için yapılacak tamamlama isteğinin parametreleri aşağıdaki gibidir:

Parametre Adı Tipi Her Zaman Mevcut Açıklama
paymentId long Evet Ödemeye ilişkin olarak ÖderoPay API tarafından türetilen ve callbackUrl'e iletilen ödeme ID'si

Ödeme Tamamlama Dönüş Parametreleri

3D Secure ile yapılan ödemelerin tamamlama isteklerine verilen cevap, standart bir ödeme ile eşdeğer olup, ödemeye ilişkin detayları içerir. Bu cevabın formatı ve içerdiği parametreler için bkz. Ödeme Alma - Dönüş Parametreleri