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şlatmak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.
| HTTP Metod | URL |
|---|---|
POST |
/payment/v1/checkout-payments/init |
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. |
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 |
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. |
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 |
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 |
Callback URL'e iletilen token değeri ile ortak ödeme sayfası kullanılarak yapılan bir ödemenin sonucu sorgulanabilir.
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ı 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
Açık kaynak kodlu Craftgate API client'larındaki örnek kodları inceleyebilirsiniz.