Ödeme Sayfası

Ortak ödeme sayfası ile yapılan ödemeler 2 adımda gerçekleşir. Başlatma ve tamamlama. Başlatma isteğinde ÖderoPay API'sine form yaratma isteği gönderilir. Bu isteğin sonucunda istemciye 2 değer dönülür. Bu değerlerden biri token diğeri ise pageUrldir. Bu adımdan sonra pageUrl ile dönülen URL browser üzerinden açılır ya da Iframe ile gösterilir. Iframe ile gösterebilmek için bu URL değerine iframe=True parametresi eklenmelidir. Ödeme işleminin sonrasında ödeme formu oluştururken yollanan callbackUrl parametresindeki url adresi token değeri ile form submit edilir. Ortak ödeme sayfası kullanılarak kart saklama ve saklı kart ile ödeme işlemi de gerçekleştirilebilir.

Ortak Ödeme Sayfası Başlatma

URL

Ortak ödeme sayfasından ödeme başlatmak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.

HTTP Method URL
POST /payment/v1/checkout-payments/init

Ödeme Başlatma İsteği Parametreleri

Ortak ödeme sayfası 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)
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.
cardUserKey string Hayır Saklı Kart Bilgileri
currency Currency Evet Para Birimleri
paymentGroup PaymentGroup Evet Ödeme Grupları
callbackUrl string Evet• 3D Secure ile yapılan ödemelerde bankadan dönen sonucu üye işyerine iletmek için kullanılacak adres
items PaymentItem[] Evet Ö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
plan PaymentPlan Hayır•• Tüm alanlar zorunludur.

•Normal şartlarda zorunlu olmayan bu alan, Ortak ödeme sayfası ile yapılan ödemelerde zorunlu olduğu için vurgulanmıştır

••PaymentGroup tekrarlı ödemede SUBSCRIPTION bu alan zorunludur

Dönüş Parametreleri

Ortak Ödeme sayfası 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
token string Evet Ortak ödeme sayfası ve ödeme işlemi için oluşturulan unique uuid4 değeri.
pageUrl string Evet Kullanıcının gitmesi gereken sayfa adresini barındırır. Bu sayfaya browser üzerinden gidildiğinde ortak ödeme sayfası açılır.

3D Secure

Üye işyeri tarafından gönderilen ödeme formu oluşturma isteği ile başlayan 3D Secure ödeme süreci, kullanıcı doğrulaması ile devam eder.

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
token string Evet Ortak ödeme sayfası ve ödeme işlemi için oluşturulan unique uuid4 değeri.
multiPayment boolean Hayır Ödeme işleminin parçalı bir şekilde yapıldığını belirtir.
paymentIdList long[] Hayır Ödeme idsini/idlerini içeren listedir.
subscriptionId long Hayır Başarılı tekrarlı ödemenin id değeri. PaymentGroup SUBSCRIPTION olarak verildiğinde dönülür

Ödeme sorgulama

Ortak ödeme sayfası kullanılarak yapılan ödemeler token değeri ile sorgulanabilir. Sorgulama işlemi için kullanılan URL ve request, response bilgileri aşağıda verilmiştir.

URL

Ortak ödeme sayfasından ödeme başlatmak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.

HTTP Metod URL
GET /payment/v1/checkout-payments/:token

Dönüş Parametreleri

Ortak Ödeme sayfası 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
id long Evet Ödemenin ID'si
createdDate date Evet Ödemenin ilk oluşturulduğu tarih
updatedDate date Evet Ödemenin güncellenme tarihi
orderId string Evet Ödemeye ilişkin olarak türetilen ayrıştırıcı ID numarası. Tamamı cüzdandan tahsil edilen ödemeler için ÖderoPay tarafından, diğer durumlarda banka tarafından türetilir
price decimal Evet Ödemenin sepet tutarı
paidPrice decimal Evet Tahsil edilen toplam tutar
walletPrice decimal Evet Cüzdandan tahsil edilen tutar
paymentType PaymentType Evet bkz: Para Birimleri
currency Currency Evet bkz: Para Birimleri
paymentStatus PaymentStatus Evet bkz: Ödeme Durumları
conversationId string Hayır Ödeme isteğinde üye işyeri tarafından gönderilen conversationId değeri
paymentCard PaymentCard Evet (bkz: Ödeme Kart ve Komisyon Bilgileri) Ödemeye ilişkin kart ve komisyon bilgileri
paymentRefunds PaymentRefund[] Evet (bkz: Ödeme İade Bilgileri) Ödemeye ilişkin iadelerin listesi
paymentTransactions PaymentTransaction[] Evet (bkz: Ödeme Kırılım Bilgileri) Ödemede yer alan kırılımların detayları

Ödeme Kart ve Komisyon Bilgileri

Tamamı cüzdandan tahsilat edilenler de dahil olmak üzere tüm ödemelerle birlikte gönderilir.

Parametre Adı Tipi Her Zaman Mevcut Açıklama
cardType CardType Hayır (bkz: Kart Tipleri) Tamamı ya da bir kısmı karttan tahsil edilen ödemelerde yer alır. Kartın tipini ifade eder
cardAssociation CardAssociation Hayır (bkz: Kart Kuruluşları) Tamamı ya da bir kısmı karttan tahsil edilen ödemelerde yer alır. Kartın bağlı olduğu kuruluşu ifade eder
cardBrand string Hayır Tamamı ya da bir kısmı karttan tahsil edilen ödemelerde yer alır. Ödeme için yapılan istekte kart bilgilerinde yer alan cardBrand ile aynı değeri taşır
cardHolderName string Hayır Tamamı ya da bir kısmı karttan tahsil edilen ödemelerde yer alır. Kart sahibinin adı ve soyadını içerir
binNumber string Hayır Tamamı ya da bir kısmı karttan tahsil edilen ödemelerde yer alır. Kart numarasının ilk 6 hanesini içerir
lastFourDigits string Hayır Tamamı ya da bir kısmı karttan tahsil edilen ödemelerde yer alır. Kart numarasının son 4 hanesini içerir
installment integer Evet Ödemenin taksit sayısını ifade eder. Alabileceği degerler: 1, 2, 3, 6, 9 ve 12
isThreeDS boolean Hayır Tamamı ya da bir kısmı karttan tahsil edilen ödemelerde yer alır. Ödemenin 3D Secure ile gerçekleşip gerçekleşmediğini ifade eder
mdStatus integer Hayır (bkz: MD Status) 3D Secure ile gerçekleşen, tamamı ya da bir kısmı karttan tahsil edilen ödemelerde yer alır. 3D Secure doğrulama durumunu ifade eder
pfCommissionRateAmount decimal Evet Ödeme aracı kuruluşu olarak ÖderoPay'in ödemeden aldığı komisyon tutarı
merchantCommissionRate decimal Evet Üye işyeri tarafından ödemeye uygulanan komisyon oranı
merchantCommissionRateAmount decimal Evet Üye işyeri tarafından ödemeden alınan toplam komisyon tutarı
error Error Hayır (bkz: Hata Bilgileri) Hatalı biçimde sonlanan ödemelerde yer alır. Hata bilgilerini içerir

Ödeme İptal Bilgileri

Tamamı iade edilen ödemelere ilişkin detay bilgileri içerir. Barındırdığı parametreler aşağıdaki tabloda listelenmiştir:

Parametre Adı Tipi Her Zaman Mevcut Açıklama
id long Evet İptal işleminin ÖderoPay tarafından türetilen ID'si
createdDate date Evet İptal tarihi
refundStatus string Evet bkz: İade Durumları
refundDestinationType RefundDestinationType Evet bkz: İade Tipleri
price decimal Evet İptal edilen tutar
refundBankPrice decimal Evet İptal sonrası karta geri yatırılan
refundWalletPrice decimal Evet İptal sonrası cüzdana geri yatırılan
conversationId string Evet İptal isteğinde üye işyeri tarafından gönderilen conversationId değeri
paymentType PaymentType Evet (bkz: Ödeme Tipleri) İptal edilen ödemenin tahsilat tipi
error Error Hayır (bkz: Hata Bilgileri) İptalin başarısız olduğu durumda yer alır. Hata bilgilerini içerir

Ödeme Kırılım Bilgileri

Ödeme isteği yapılırken gönderilen kırılım bilgileri ile, ödemenin bu kırılımlar bazındaki fiyatlama ve para gönderimleri bilgisi ile, kırılıma ilişkin iade kalemlerini içerir

Parametre Adı Tipi Her Zaman Mevcut Açıklama
id long Evet Ödeme kırılımının ID'si
createdDate date Evet Ödeme kırılımının oluşturulduğu tarih
externalId string Hayır Ödeme isteğinde gönderilen, ödeme kırılımına ilişkin dış ID değeri
transactionStatus TransactionStatus Evet (bkz: Para Gönderimi Durumları) Kırılıma ilişkin para gönderim durumunu ifade eden değer
transactionStatusDate date Evet Kırılıma ilişkin para gönderim durumunun değiştiği son tarihi ifade eder
price decimal Evet Ödeme kırılımının sepetteki tutarı
paidPrice decimal Evet Ödeme için tahsil edilen toplam tutarın, ilgili kırılıma düşen payı
walletPrice decimal Evet Ödeme için cüzdandan tahsil edilen toplam tutarın, ilgili kırılıma düşen payı
merchantPayoutAmount decimal Evet Ödemeye ilişkin üye işyerine gönderilecek olan paranın, ilgili kırılıma düşen payı
subMerchantId long Hayır Ödeme kırılımının ilişkili olduğu alt üye işyeri ID'si
subMerchantName string Evet Ödeme kırılımının bir alt üye işyeriyle ilişkili olduğu durumda yer alır. İlgili üye işyerinin adını içerir
subMerchantPrice decimal Evet Ödeme kırılımının bir alt üye işyeriyle ilişkili olduğu durumda yer alır. Ödeme tutarından alt üye işyerine aktarılacak toplam tutarın, ilgili kırılıma düşen payıdır
subMerchantPayoutRate decimal Evet Ödeme kırılımının bir alt üye işyeriyle ilişkili olduğu durumda yer alır. Ödemeye ilişkin alt üye işyerine gönderilecek olan paranın, üye işyerine gönderilecek paraya olan oranıdır
subMerchantPayoutAmount decimal Evet Ödeme kırılımının bir alt üye işyeriyle ilişkili olduğu durumda yer alır. Ödemeye ilişkin alt üye işyerine gönderilecek olan tutarı ifade eder
payout Payout Evet (bkz: Ödeme Kırılımı Para Gönderim Dağılımı) Ödeme kırılıma ilişkin para gönderim tutarlarının üye işyeri, alt üye işyeri ve ÖderoPay arasındaki dağılımını içerir
paymentTransactionCard PaymentTransactionCard Evet (bkz: Ödeme Kırılımı Kart ve Komisyon Bilgileri) Ödeme kırılımına ilişkin kart ve komisyon bilgilerini içerir
paymentTransactionRefunds PaymentTransactionRefund[] Evet (bkz: Ödeme Kırılımı İade Bilgileri) Ödeme kırılımına ilişkin kısmi ve tam iade bilgilerinin listesi

Ödeme Kırılımı Kart ve Komisyon Bilgileri

Ödeme kırılımına ilişkin kart ve komisyon bilgilerini içerir

Parametre Adı Tipi Her Zaman Mevcut Açıklama
merchantCommissionRate decimal Evet Üye işyeri tarafından ödemeye uygulanan komisyon oranı
merchantCommissionRateAmount decimal Evet Üye işyeri tarafından ödemedem alınan komisyon tutarından ödeme kırılımına düşen pay
pfCommissionRateAmount decimal Evet Ödeme aracı kuruluşu olarak ÖderoPay'in ödemeden aldığı komisyon tutarından ödeme kırılımına düşen pay

Ödeme Kırılımı Para Gönderim Dağılımı

Ödemeye ilişkin olarak yapılacak para gönderiminin, bir kırılım özelindeki payının üye işyeri, alt üye işyeri ve ÖderoPay arasındaki dağılımını içerir.

Para dağıtımının para birimi her zaman TRY'dir, dolayısı ile diğer para birimleri ile yapılan ödemelerde kur farkı oluşacaktır. Bu farklar pfConversionRate ve pfConversionRateAmount alanlarında belirtilmiştir.

Parametre Adı Tipi Her Zaman Mevcut Açıklama
paidPrice decimal Evet Ödeme için tahsil edilen toplam tutarın, ilgili kırılıma düşen payı
currency Currency Evet bkz: Para Birimleri
merchantPayoutAmount decimal Evet Ödemeye ilişkin üye işyerine gönderilecek olan paranın TL cinsinden değerinin, ilgili kırılıma düşen payı
subMerchantPayoutAmount decimal Evet Ödemeye ilişkin alt üye işyerine gönderilecek olan paranın TL cinsinden değerinin, ilgili kırılıma düşen payı
pfCommissionRateAmount decimal Evet Ödemeye ilişkin alt üye işyerine gönderilecek olan paranın TL cinsinden değerinin, ilgili kırılıma düşen payı
pfConversionRate decimal Evet TRY'den farklı bir para birimiyle yapılan ödemelerin para gönderimlerinde ÖderoPay'in baz aldığı kur farkı oranı. TRY ödemelerde 0'dır
pfConversionRateAmount decimal Evet TRY'den farklı bir para birimiyle yapılan ödemelerin para gönderimlerinde ÖderoPay'in aldığı kur farkı. TRY ödemelerde 0'dır

Ödeme Kırılımı İade Bilgileri

Ödeme kırılımına ilişkin tam ve kısmi, başaraılı ya da başarısız iade bilgileridir

Parametre Adı Tipi Her Zaman Mevcut Açıklama
id long Evet İadeye ilişkin ÖderoPay tarafından türetilen ID
createdDate date Evet İadenin gerçekleştiği tarih
refundStatus string Evet bkz: İade Durumları
refundDestinationType RefundDestinationType Evet bkz: İade Tipleri
refundPrice decimal Evet İade edilen tutar
refundBankPrice decimal Evet İade sonrası karta geri yatırılan
refundWalletPrice decimal Evet İade sonrası cüzdana geri yatırılan
conversationId string Evet İade isteğinde üye işyeri tarafından gönderilen conversationId değeri
paymentType PaymentType Evet (bkz: Ödeme Tipleri) İade edilen ödemenin tahsilat tipi
isAfterSettlement boolean Evet İadenin, kırılımın para gönderimi sonrasında gerçekleşip gerçekleşmediği
error Error Hayır (bkz: Hata Bilgileri) İadenin başarısız olduğu durumda yer alır. Hata bilgilerini içerir