Ödeme almak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.
HTTP Metod | URL |
---|---|
POST |
/payment/v1/card-payments |
Ödeme gerçekleştirmek için yapılacak isteklerde gönderilmesi beklenen parametreler aşağıdaki tablo ve alt başlıklar altında listelenmiştir.
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. Sipariş numarası ile kullanmanız sonradan işlemleri incelemenize yardımcı olacaktı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, karttan çekilecek nihai tutar. Tamamı ya da bir kısmı cüzdandan tahsil edilen ödemelerde cüzdandan tahsil edilecek tutar da bu tutara dahildir. İşlemde vade farkı var ise vade farkı eklenmiş tutar bu parametreye girilmelidir. |
walletPrice |
decimal |
Evet | buyerMemberId 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 buyerMemberId bulunmadığı durumda 0 olarak gönderilebilir. (Varsayılan: 0 ) |
installment |
number |
Evet | Ödemenin tahsil edileceği taksit sayısı. Tek çekim için 1 olarak gönderilebilir. |
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. |
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. |
clientIp |
string |
Hayır | Ödeme yapan alıcının IP adresi. |
card |
Card |
Hayır | (bkz. Kart Bilgileri) Tahsilatın gerçekleştirileceği kart bilgileri. Tamamı cüzdandan tahsil edilecek ödemelerde (yani paidPrice 'in walletPrice 'a eşit olduğu ödemeler) gönderilmemelidir |
posAlias |
string |
Hayır | Ödemeyi geçirmek istediğiniz pos'un alias değeri. Ödemenin geçeceği pos'a kendiniz karar verdiyseniz bu parametre ile ilgili posdan ödeme alabilirsiniz. |
fraudParams |
FraudCheckParameters |
Hayır | (bkz. Fraud Kontrol Parametreleri) Fraud kontrolü için gönderilebilecek ek parametreler |
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 |
additionalParams |
map<string, map> |
Hayır | Ödemeye ait gönderilmek istenen ek parametreler. bkz: Ödeme Ek Parametreleri |
Tamamı ya da bir kısmı kartla yapılan ödemelerde kart bilgisi gönderilmesi zorunludur. Bu bilgiler bir kredi kartı, debit kart ya da prepaid kartın bilgileri olabileceği gibi, daha önceden saklanmış bir karta ilişkin tanımlayıcı bilgiler de olabilir.
Gönderilen kart bilgilerindeki cardUserKey
alanı doluysa Saklı Kart Bilgileri bölümündeki alanlar geçerlidir, diğer durumlar için bkz. Kredi Kartı, Debit Kart ya da Prepaid Kart Bilgileri.
Sigorta sektöründeyseniz ve kart numarasının ilk 6, son 4 hanesi ve TCKN/VKN bilgileri ile ödeme gerçekleştirilmek isteniyorsa Sadece Sigorta Sektörüne Özel İlk 6, Son 4 ve TCKN ile Ödemede Gerekli Kart Bilgileri bölümündeki alanlar geçerlidir. Bu özelliğin kullanılabilmesi için Sanal Posunuzun bu özelliği desteklemesi gereklidir.
Parametre Adı | Tipi | Zorunlu | Açıklama |
---|---|---|---|
cardAlias |
string |
Hayır | Başarılı ödemeden sonra kart kaydedilecekse karta verilecek isim |
cardHolderName |
string |
Evet | Kart sahibinin adı/soyadı Şu özel karakterler ve sayısal değerler içermemelidir: \<>"%;&+()|=! |
cardNumber |
string |
Evet | Kart numarası |
expireYear |
string |
Evet | Kartın son kullanım tarihinin yılı |
expireMonth |
string |
Evet | Kartın son kullanım tarihinin ayı |
cvc |
string |
Evet | Kart güvenlik kodu |
storeCardAfterSuccessPayment |
boolean |
Hayır | Ödeme sonrası kart kaydedilsin mi? (Varsayılan: false ) |
cardUserKey |
string |
Hayır | Daha önceden kart sakladıysanız, Craftgate tarafından üretilip size dönülen kart kullanıcı anahtarını bu parametrede göndermelisiniz. İlk defa kart saklanıyor ise bu alan gönderilmemelidir. |
loyalty |
Loyalty |
Hayır | Ödeme esnasında kullanılmak istenen ödül bilgileri (bkz: Ödül ve Puan Kullanımı) |
Parametre Adı | Tipi | Zorunlu | Açıklama |
---|---|---|---|
cardUserKey |
string |
Evet | Kart kullanıcı anahtarı. Craftgate tarafından üretilir ve kart saklama isteği sonrası üye işyerine dönülür. Kişi bazlı özeldir. Örneğin; Alican kişisi cardUserKey ile ifade edilir. |
cardToken |
string |
Evet | Kart anahtarı. Craftgate tarafından üretilir ve kart saklama isteği sonrası üye işyerine dönülür. Kart bazlı özeldir. CardUserKey ile birlikte kullanılır. Örneğin; Alican(cardUserKey) kişisinin Garanti Kredi kartı(cardToken) gibi. |
loyalty |
Loyalty |
Hayır | Ödeme esnasında kullanılmak istenen ödül bilgileri (bkz: Ödül ve Puan Kullanımı) |
Parametre Adı | Tipi | Zorunlu | Açıklama |
---|---|---|---|
binNumber |
string |
Evet | Kartın ilk 6 hanesi |
lastFourDigits |
string |
Evet | Kartın son 4 hanesi |
cardHolderIdentityNumber |
string |
Evet | Kart sahibine ait TCKN veya VKN |
Tüm ödemelerde 1 ya da 1'den fazla kırılım gönderilmesi zorunludur. Gönderilen kırılımların price
alanlarının toplamı, ödemenin price
alanındaki değere eşit olmalıdır.
Parametre Adı | Tipi | Zorunlu | Açıklama |
---|---|---|---|
name |
string |
Hayır | Ödemeye ilişkin ürün ya da hizmetin adı |
price |
decimal |
Evet | İlgili ürün ya da hizmetin sepet tutarı |
externalId |
string |
Hayır | İlgili ürün ya da hizmeti ifade eden dış ID değeri. Genellikle üye işyeri sisteminde bu kırılıma ilişkin ID değeri kullanılır |
subMerchantMemberId |
number |
Hayır | Ürün ya da hizmeti sağlayan satıcı ID'si |
subMerchantMemberPrice |
decimal |
Hayır | Ödemeden satıcıya aktarılacak tutar. subMerchantMemberId alanı doluysa gönderilmesi gerekmektedir |
Parametre Adı | Tipi | Zorunlu | Açıklama |
---|---|---|---|
buyerExternalId |
string |
Hayır | Ödeme sırasında Fraud kontrolüne dahil edilmesi istenen alıcıya özel üretilmiş unique değer |
buyerPhoneNumber |
string |
Hayır | Ödeme sırasında Fraud kontrolüne dahil edilmesi istenen alıcının telefon numarası |
buyerEmail |
string |
Hayır | Ödeme sırasında Fraud kontrolüne dahil edilmesi istenen alıcının email adres |
Parametre Adı | Tipi | Zorunlu | Açıklama |
---|---|---|---|
paymentProvider |
map<string, map> |
Hayır | Başka bir ödeme kuruluşunda saklı kartla ödeme almak istendiğinde gönderilmesi gerekir. İçerisinde cardUserKey ve cardToken gönderilmesi beklenir. |
Örnek olarak İYZİ ÖDEME VE ELEKTRONIK PARA HIZMETLERI
kuruluşunda saklı bir kart ile ödeme yapılmak istenildiğinde, ödeme isteği içersinde card
alanı yerine aşağıdaki JSON bloğu gönderilmeldir. Buradaki cardUserKey
ve cardToken
iyzico'ya iletilip oradaki saklı kartla ödeme alınmaya çalışılır.
{
...,
"paymentProvider": {
"cardUserKey": "aaf4e557-8bd0-47d6-86ae-7aa59c30c5a2",
"cardToken" : "82b413a5-605f-4389-83cf-bc933da9e5df"
}
}
Ödeme alındığı durumda dönüş parametrelerinde karta ait aşağıdaki bilgiler boş kalacaktır.
binNumber
lastFourDigits
cardType
cardAssociation
cardBrand
Ödeme işleminin sonucunda dönen parametreler de 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 | Açıklama |
---|---|---|
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 |
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 |
bkz: Ödeme Tipleri |
paymentGroup |
PaymentGroup |
bkz: Ödeme Grupları |
paymentSource |
PaymentSource |
bkz: Ödeme Kaynakları |
paymentStatus |
PaymentStatus |
bkz: Ödeme Durumu |
paymentPhase |
PaymentPhase |
bkz: Ödeme Fazları |
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ı |
authCode |
string |
Ödemeye ilişkin banka tarafından verilen authCode değeri. Tamamı cüzdan ile ödenen ödemelerde boş gelir |
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 |
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 |
cardAssociation |
CardAssociation |
(bkz: Kart Kuruluşları) Kartı sağlayan kart kuruluşuunu ifade eder. Tamamı cüzdan ile ödenen ödemelerde boş gelir |
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 bkz: Ödeme POS Bilgisi |
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ı) |
paymentTransactions |
PaymentTransaction[] |
bkz: Ödeme Kırılımı Dönüş Bilgileri |
additionalData |
map<string, map> |
bkz: Ödeme Sonucu Ek Bilgiler |
Ö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
Parametre Adı | Tipi | Açıklama |
---|---|---|
id |
number |
Ödeme kırılımının ID'si |
externalId |
string |
Ödeme isteğinde gönderilen, ödeme kırılımına ilişkin dış ID değeri |
name |
string |
Ödeme isteğinde gönderilen, ödeme kırılımının ifade ettiği ürün ya da hizmetin adı |
price |
decimal |
Ödeme kırılımının sepetteki tutarı |
paidPrice |
decimal |
Ödeme için tahsil edilen toplam tutarın, ilgili kırılıma düşen payı |
walletPrice |
decimal |
Ödeme için cüzdandan tahsil edilen toplam tutarın, ilgili kırılıma düşen payı |
merchantCommissionRate |
decimal |
Son kullanıcıya yansıtılan vade farkı oranı |
merchantCommissionRateAmount |
decimal |
Son kullanıcıya yansıtılan vade farkı tutarının ödeme kırılımına düşen payı |
merchantPayoutAmount |
decimal |
Ödemeye ilişkin üye işyerine gönderilecek olan paranın, ilgili kırılıma düşen payı |
subMerchantMemberId |
number |
Ödeme kırılımının ilişkili olduğu satıcı ID'si |
subMerchantMemberPrice |
decimal |
Ödeme kırılımının bir satıcılarla ilişkili olduğu durumda yer alır. Ödeme tutarından satıcıya aktarılacak toplam tutarın, ilgili kırılıma düşen payıdır |
subMerchantMemberPayoutRate |
decimal |
Ödeme kırılımının bir satıcılarla ilişkili olduğu durumda yer alır. Ödemeye ilişkin satıcıya gönderilecek olan paranın, üye işyerine gönderilecek paraya olan oranıdır |
subMerchantMemberPayoutAmount |
decimal |
Ödeme kırılımının bir satıcılarla ilişkili olduğu durumda yer alır. Ödemeye ilişkin satıcıya gönderilecek olan tutarı ifade eder |
transactionStatus |
TransactionStatus |
(bkz: Kırılım Onay Durumları) Kırılıma ilişkin onay durumunu ifade eden değer |
blockageResolvedDate |
date |
Para gönderimi için gereken blokaj süresinin sonlanacağı tarih |
payout |
Payout |
(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, satıcı ve Craftgate arasındaki dağılımını içerir |
Ödemeye ilişkin olarak yapılacak para gönderiminin, bir kırılım özelindeki payının üye işyeri ve satıcı arasındaki dağılımını içerir.
Para dağıtımının para birimi her zaman TRY
'dir.
Parametre Adı | Tipi | Açıklama |
---|---|---|
paidPrice |
decimal |
Ödeme için tahsil edilen toplam tutarın, ilgili kırılıma düşen payı |
parity |
decimal |
Döviz paritesi, TRY ödemeler için 1 olacaktır. |
currency |
Currency |
bkz: Para Birimleri |
merchantPayoutAmount |
decimal |
Ödemeye ilişkin üye işyerine gönderilecek olan paranın TL cinsinden değerinin, ilgili kırılıma düşen payı |
subMerchantMemberPayoutAmount |
decimal |
Ödemeye ilişkin satıcıya gönderilecek olan paranın TL cinsinden değerinin, ilgili kırılıma düşen payı |
Parametre Adı | Tipi | Açıklama |
---|---|---|
campaignUrl |
string |
Garanti bankası ile ek taksit anlaşması olan üye işyerleri için geçerli parametredir. Taksitli işlemler sonucunda ek taksit yapabilmesi için alıcıya gösterilecek URLi içerir. |
Parametre Adı | Tipi | Açıklama |
---|---|---|
id |
number |
Üye işyeri POS ID'si |
name |
string |
Üye işyeri POS adı |
alias |
string |
Üye işyeri POS alias'ı |
bankId |
number |
Üye işyeri POSunun bağlı olduğu banka ID'si |
Açık kaynak kodlu Craftgate API client'larındaki örnek kodları inceleyebilirsiniz.