Ortak Ödeme Sayfası ile Ödeme

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.

Kart saklama

Ortak ödeme sayfası ile ödeme yapıldığında kart saklamak için kullanıcının ödeme sayfasındaki kartımı sakla seçeneğini seçmiş olması gerekmektedir. Ortak ödeme sayfası üzerinden olmayan ödemelerde de kart saklanabilir bkz: Kart Saklama

Saklı kart ile ödeme

Kullanıcının var olan saklı kartlarından biri ile ödeme gerçekleştirebilmesi için kullanıcıya ait olan cardUserKey değerinin istek ile beraber iletilmesi gerekmektedir. Kullanıcının ortak ödeme sayfası kullanarak ya da normal yollarla yaptığı ödemelerde sakladığı kartlar ortak ödeme sayfasında listelenecektir.

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 Metod	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	Kullanıcının saklı kart anahtarı bkz: Saklı Kart Bilgileri
`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)
`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
`plan`	`PaymentPlan`	Hayır**	(bkz: Tekrarlı Ödeme Məlumatları Terkralı ödenme bilgileri. 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ı ödemese (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.
`subscriptionId`	`long`	Hayır	Uğurlu tekrarlı ödemenin id dəyəri. PaymentGroup SUBSCRIPTION olsa, bu alan dönüyor.

Ö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=:token`

Dönüş Parametreleri

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

Örnek Kodlar

Açık kaynak kodlu ÖderoPay API client'larındaki örnek kodları inceleyebilirsiniz