Ortak Ödeme Sayfası ile Ödeme Alma

Ortak Ödeme sayfası ile yapılan ödemeler 2 adımda gerçekleşir: başlatma ve tamamlanma. Başlatma isteği sonucu Craftgate API'sinden bir token değeri ve ödeme sayfasının URL'ini barındıran pageUrl değeri dönecektir. Daha sonra kullanıcı bu URL'e giderek ödemeyi tamamlar. Tamamlanan ödemenin durumu başlatma isteğinde verilen callbackUrl parametresindeki adrese iletilir ve sürecin uçtan uca tamamlanmasını sağlar. callbackUrl parametresine ek olarak eğer merchantWebhookUrl parametresi gönderilmiş ise, bu adrese sunucu tarafından HTTP POST methodu ile json formatında token bilgisi iletilir.

Ortak Ödeme Sayfası ile Ödeme Başlatma

URL

Ortak ödeme sayfası ile ö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 ve kart bilgileri beklenmez. İlgili kullanıcının saklı kartlarını kullanabilmesi için cardUserKey parametresi doldurulabilir. Bu bağlamda ortak ödeme sayfası ile bir ödeme başlatmak için 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
externalId string Hayır Genellikle üye işyeri tarafındaki, ödemeye ilişkin sipariş numarası veya sepet numarası olarak kullanılır. Daha sonradan sorgulama servislerinde bu id ile sorgulama yapabilirsiniz.
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
buyerMemberId number Hayır Ödemenin ilişkilendirildiği alıcı ID'si. Üye işyerinin kendi sistemlerindeki ID değerini değil, Craftgate sistemlerindeki ID değerini ifade eder
currency Currency Evet bkz: Para Birimleri Ödemenin tahsil edileceği para birimi
paymentGroup PaymentGroup Hayır bkz: Ödeme Grupları
paymentPhase PaymentPhase Hayır bkz: Ödeme Fazları
paymentChannel string Hayır Genellikle üye işyeri tarafındaki, ödemenin alındığı kanal veya ödemeye özel bir bilgi tutmak için kullanılır. Daha sonradan sorgulama servislerini kullanarak bu değer ile sorgulama yapabilirsiniz.
callbackUrl string Evet Ortak ödeme sayfasındaki akış tamamlandığında çağırılacak URL adresi
merchantWebhookUrl string Hayır Ortak ödeme sayfasındaki akış tamamlandığında, sunucu tarafından token bilgisinin iletileceği merchant webhook adresi. callbackUrl adresine yapılan istek tarayıcı üzerinden gerçekleştirilmektedir, son kullanıcının bu akışı durdurması veya kullanıcının internetinde yaşanabilecek sorunlardan dolayı callbackUrl adresine yapılan istekler başarısız olabilir. Eğer merchantWebhookUrl parametresi gönderildi ise ortak ödeme sayfası ile ödeme işlemi tamamlandı bilgisi bu adrese ayrıca iletilecektir.
cardUserKey string Hayır Kart kullanıcı anahtarı
enabledInstallments number[] Hayır Eğer yollanırsa kullanıcıya bu değerlere ait taksit olanakları ödeme ekranında gösterilir. Eğer ilgili pos üzerinde bu taksit seçenekleri aktif değilse taksit seçenekleri gösterilmez. Tek taksit seçeneği her zaman varmış gibi kabul edilir. Yollanmadığı durumda tüm taksit seçenekleri geçerlidir.
allowOnlyCreditCard boolean Hayır Eğer true olarak yollanırsa kullanıcıdan sadece kredi kartı ile ödeme alınır
allowOnlyStoredCards boolean Hayır Eğer true olarak yollanırsa kullanıcı sadece saklı kartlarını kullanarak ödeme yapabilir. Bu değer true olarak yollandığı takdirde cardUserKey parametresi gönderilmelidir.
alwaysStoreCardAfterPayment boolean Hayır Eğer true olarak yollanırsa kullanıcının ödeme için kullandığı kart saklanacaktır. Bu değer true olarak yollandığı takdirde allowOnlyStoredCards parametresi gönderilmemelidir.
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
masterpassGsmNumber string Hayır (bkz. Masterpass) Eğer kullanıcının Masterpass ile ödeme yapabilmesi isteniyorsa, kullanıcının Masterpass ile ilişkilendirilmiş telefon numarası 90 ile başlayacak şekilde girilmelidir. Girmediğiniz takdirde ya da girmiş olduğunuz telefon numarası Masterpass ile daha önce ilişkilendirilmediyse, ödeme formunda Masterpass tabı açılmayacaktır.
enabledPaymentMethods PaymentMethod[] Hayır (bkz. Masterpass) Ortak ödeme sayfasında görünmesi istenen ödeme yöntemleri listelenir. Eğer sadece [CARD] olarak yollandığında sadece kartlı ödeme kabul edilirken, [CARD, MASTERPASS] olarak yollandığında hem kartlı ödeme hem Masterpass tabları gösterilir. Hiç gönderilmediğinde mevcuttaki tüm ödeme yöntemleri listelenir.

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ı başlangıç isteği için oluşturulan alfanumerik değer
pageUrl string Evet Ortak ödeme sayfası başlagıç isteği üzerine oluşturulan ve kullanıcının ödeme yapması için ziyaret etmesi gereken sayfa URL değeri

Ödeme sayfası için opsiyonel parametreler

pageUrl alnında dönen URL'e ek olarak aşağıdaki parametreler eklenebilir.

Parametre Adı Açıklama
iframe Eğer true ise sayfa iframe olarak gösterilir.
animatedCard Eğer true ise sayfada kullanıcı inputu ile şekillenen görsel bir kredi kartı komponenti yer alır.

Callback URL'e İletilen Parametreler

Aşağıdaki parametreler form variable olarak HTTP POST metodu kullanılarak iletilir. Doğrulama sonrası Craftgate 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ı başlangıç isteği için oluşturulan alfanumerik değer

Merchant Webhook URL'e İletilen Parametreler

Aşağıdaki parametreler json olarak HTTP POST metodu kullanılarak iletilir. Doğrulama sonrası Craftgate tarafından merchantWebhookUrl'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ı başlangıç isteği için oluşturulan alfanumerik değer

Ortak Ödeme Sayfası Ödemesi Sorgulama

Callback URL'e iletilen token değeri ile ortak ödeme sayfası kullanılarak yapılan bir ödemenin sonucu sorgulanabilir.

URL

Ortak ödeme sayfası ile yapılan ödemeleri sorgulamak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.

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

Ortak Ödeme Sayfası Ödemesi Sorgulama Dönüş Parametreleri

Ortak Ödeme Sayfası ile yapılan ödemelerin sorgulama 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

Örnek Kodlar

Açık kaynak kodlu Craftgate API client'larındaki örnek kodları inceleyebilirsiniz.

Ortak Ödeme Sayfası Ödemesi Başlatma

Ortak Ödeme Sayfası Ödemesi Sorgulama