Ana içeriğe geç

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.

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

conversationId
string

İ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

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

Ö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
zorunlu

Toplam ödeme tutarı. Sepetteki ürün/hizmet tutarları toplamının bu tutara eşit olması gerekmektedir

paidPrice
decimal
zorunlu

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

Ö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
zorunlu

bkz: Para Birimleri Ödemenin tahsil edileceği para birimi

Değerler:
TRY
USD
EUR
GBP
CNY
ARS
BRL
AED
IQD
AZN
KZT
paymentGroup
PaymentGroup
Değerler:
PRODUCT
LISTING_OR_SUBSCRIPTION
paymentPhase
PaymentPhase

bkz: Ödeme Fazları - Provizyon kapama için bkz: Provizyon Kapama

Değerler:
AUTH
PRE_AUTH
POST_AUTH
paymentChannel
string

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
zorunlu

Ortak ödeme sayfasındaki akış tamamlandığında çağırılacak URL adresi

cardUserKey
string

Kart kullanıcı anahtarı

enabledInstallments
number[]

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

Eğer true olarak yollanırsa kullanıcıdan sadece kredi kartı ile ödeme alınır

allowOnlyStoredCards
boolean

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

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

Eğer true olarak yollanırsa Ortak Ödeme Formu üzerinden sadece ticari kart sahipleri için taksit seçenekleri gösterilecektir.

forceAuthForNonCreditCards
boolean

Eğer true olarak yollanırsa Ortak Ödeme Formu üzerinden ön provizyon PRE_AUTH kullanılmak isteniyorsa, kredi kartı dışındaki kart tiplerine provizyon ödemesi AUTH zorunlu kılınır.

forceThreeDS
boolean

Eğer true olarak yollanırsa kullanıcının 3DS ödeme gerçekleştirmesi zorunlu kılınır.

depositPayment
boolean

Eğer true olarak yollanırsa ödeme cüzdan hesabına aktarılır. Bu alan true olarak yollandığında buyerMemberId bilgisi iletilmelidir. items parametresinin dolu olması gerekmemektedir.

ttl
long

Bu istekte başlatılan ödeme isteğinin dakika cinsinden ne kadar süre kullanılabileceğini belirleyen parametre.

items
PaymentItem[]
zorunlu

Ö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

(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

(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

(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[]

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:

token
string

Ortak ödeme sayfası başlangıç isteği için oluşturulan alfanumerik değer

pageUrl
string

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

tokenExpireDate
date

Ortak ödeme sayfası için geçerlilik süresi

Ödeme sayfası için opsiyonel parametreler

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

Parametre AdıAçıklama
iframeEğer true ise sayfa iframe olarak gösterilir.
animatedCardEğ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:

token
string

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:

token
string

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.

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

id
number

Ödemenin ID'si. Bu değer ödeme isteği için Craftgate tarafından belirlenen eşsiz değerdir. Veritabanınızda sipariş bilgileri ile eşleştirip saklamayı unutmayınız.

createdDate
date

Ödemenin gerçekleştirildiği tarih

price
decimal

Ödemenin toplam sepet tutarı

paidPrice
decimal

Müşterinin ödediğ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

Cüzdandan tahsil edilen tutar

currency
Currency

Ödemeye ilişkin para birimi. bkz: Para Birimleri

Değerler:
TRY
USD
EUR
GBP
CNY
ARS
BRL
AED
IQD
AZN
KZT
buyerMemberId
number

Alıcı üyeyle ilişkilendirilmiş ödemelerde yer alan, ilgili üyenin ID'sini belirten değer

installment
number

Ödemenin taksit sayısı

conversationId
string

Üye işyeri tarafından ödeme isteği içerisinde gönderilen conversationId değeri

externalId
string

Üye işyeri tarafından ödeme isteği içerisinde gönderilen externalId değeri

paymentType
PaymentType
Değerler:
CARD_PAYMENT
DEPOSIT_PAYMENT
WALLET_PAYMENT
CARD_AND_WALLET_PAYMENT
BANK_TRANSFER
APM
paymentGroup
PaymentGroup
Değerler:
PRODUCT
LISTING_OR_SUBSCRIPTION
paymentSource
PaymentSource
Değerler:
API
CHECKOUT_FORM
PAY_BY_LINK
paymentStatus
PaymentStatus
Değerler:
FAILURE
SUCCESS
INIT_THREEDS
CALLBACK_THREEDS
WAITING
paymentPhase
PaymentPhase
Değerler:
AUTH
PRE_AUTH
POST_AUTH
paymentChannel
string

Üye işyeri tarafından ödeme isteği içerisinde gönderilen paymentChannel değeri

isThreeDS
boolean

Ödemenin 3D Secure ile gerçekleştirilip gerçekleştirilmediği

merchantCommissionRate
decimal

Son kullanıcıya yansıtılan vade farkı oranı

merchantCommissionRateAmount
decimal

Son kullanıcıya yansıtılan vade farkı tutarı. paidPrice ile price arasındaki farka eşittir

bankCommissionRate
decimal

Banka komisyon oranı

bankCommissionRateAmount
decimal

Banka komisyon tutarı

cardUserKey
string

Ödeme esnasında kart saklanmak istenmiş ise kart saklanır ve bu alan dolu gelir. Başarılı ödeme sonrası kaydedilen kartın saklı kart kullanıcı anahtarını ifade eder. Üye işyeri tarafından müşteriyle ilişkilendirilerek saklanmalıdır

cardToken
string

Ödeme esnasında kart saklanmak istenmiş ise kart saklanır ve bu alan dolu gelir. Başarılı ödeme sonrası kaydedilen kartın saklı kart anahtarını ifade eder. Üye işyeri tarafından müşteriyle ilişkilendirilerek saklanmalıdır

paidWithStoredCard
boolean

Ödemenin saklı kartla gerçekleştirilip gerçekleştirilmediğini belirtir

binNumber
string

Kartın ilk 8 hanesini belirtir. Tamamı cüzdan ile ödenen ödemelerde boş gelir.

lastFourDigits
string

Kartın son 4 hanesini belirtir. Tamamı cüzdan ile ödenen ödemelerde boş gelir

cardHolderName
string

Kart sahibinin adı/soyadı

bankCardHolderName
string

Bankada kayıtlı olan kart sahibi adı/soyadı. Bazı durumlarda PF poslarında dönüş null olabilir

authCode
string

Ödemeye ilişkin banka tarafından verilen authCode değeri. Tamamı cüzdan ile ödenen ödemelerde boş gelir. Bazı durumlarda PF poslarında dönüş null olabilir

hostReference
string

Ödemeye ilişkin banka tarafından verilen hostReference değeri. Tamamı cüzdan ile ödenen ödemelerde boş gelir

transId
string

Ödemeye ilişkin banka tarafından verilen transId değeri. Tamamı cüzdan ile ödenen ödemelerde boş gelir. Bazı durumlarda PF poslarında dönüş null olabilir

orderId
string

Ödemeye ilişkin banka tarafından verilen orderId değeri

cardType
CardType

(bkz: Kart Tipleri) Kartın tipini ifade eder. Tamamı cüzdan ile ödenen ödemelerde boş gelir

Değerler:
CREDIT_CARD
DEBIT_CARD
PREPAID_CARD
cardAssociation
CardAssociation

Kartı sağlayan kart kuruluşuunu ifade eder. Tamamı cüzdan ile ödenen ödemelerde boş gelir

Değerler:
VISA
MASTER_CARD
AMEX
TROY
JCB
UNION_PAY
MAESTRO
DISCOVER
DINERS_CLUB
cardBrand
string

Ödemenin alındığı kartın ailesini belirtir. Tamamı cüzdan ile ödenen ödemelerde boş gelir

requestedPosAlias
string

Üye işyeri tarafından ödeme isteği içerisinde gönderilen posAlias değeri

pos
MerchantPos

Ödemenin alındığı pos bilgileri

loyalty
Loyalty

Ödemede kullanılmış olan ödül bilgileri (bkz: Ödül ve Puan Kullanımı)

fraudId
number

Şüpheli işlem olarak belirlenmesi durumunda şüpheli işlem kaydına ait id bilgisi (bkz: Şüpheli İşlem Yönetimi)

fraudAction
FraudAction

Şüpheli işlem olarak belirlenmesi durumunda şüpheli işlem kaydına ait aksiyon bilgisi (bkz: Şüpheli İşlem Aksiyonları)

Değerler:
BLOCK
REVIEW
paymentTransactions
PaymentTransaction[]

Ö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önderimi bilgilerini içerir

additionalData
map<string, map>

Ödeme sonucuna ilişkim ek bilgiler.

Ortak Ödeme Sayfası Geçerlilik Doldurma

Ortak ödeme sayfası ile ödeme başlatma isteği sonucu elde edilen token değeri kullanılarak bu değerin geçerlilik süresi doldurulabilir ve kullanılamaz hale getirilebilir.

URL

Ortak ödeme sayfası geçerlilik doldurmak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.

DELETE/payment/v1/checkout-payments/:token

Örnek Kodlar

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

Ortak Ödeme Sayfası Ödemesi Başlatma

Loading..

Ortak Ödeme Sayfası Ödemesi Sorgulama

Loading..

Ortak Ödeme Sayfası Geçerlilik Doldurma

Loading..