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.
bankOrderId string Hayır Ödeme alınırken bankaya iletilecek orderId parametresi. Opsiyonel olduğu için gönderilmemesi ve orderId değerinin Craftgate tarafından üretilmesi önerilir.
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ı - Provizyon kapama için bkz: Provizyon Kapama
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
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.
allowInstallmentOnlyCommercialCards boolean Hayır Eğer true olarak yollanırsa Ortak Ödeme Formu üzerinden sadece ticari kart sahipleri için taksit seçenekleri gösterilecektir.
forceThreeDS boolean Hayır Eğer true olarak yollanırsa kullanıcının 3DS ödeme gerçekleştirmesi zorunlu kılınır.
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.
masterpassUserId string Hayır (bkz. Masterpass) Eğer kullanıcının Masterpass ile ödeme yapabilmesi isteniyorsa, ve kullanıcının Masterpass hesabı, üye işyeri ile daha önce Craftgate entegrasyonu dışında bir ortam üzerinden ilişkilendirildiyse, ilişkilendirme aşamasında kullanılan userId değeri.
apmUserIdentity string Hayır (bkz. Payoneer) Eğer kullanıcının Payoneer ile ödeme yapabilmesi isteniyorsa, ödeme yapacak olan kullanıcı ile ilişkili eşsiz değer.
enabledPaymentMethods PaymentMethod[] Hayır Ortak ödeme sayfasında görünmesi istenen ödeme yöntemlerini bu parametre ile yönetebilirsiniz. Eğer sadece [CARD] olarak yollanırsa kullanıcı sadece kartla ödeme yapabilir. Listelenmesini istediğiniz ödeme yöntemleri için (bkz. Ödeme Yöntemleri). 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