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ş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 |
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
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 |
Ü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.
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 |
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.
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 |
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 |
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
Açık kaynak kodlu ÖderoPay API client'larındaki örnek kodları inceleyebilirsiniz