Ödeme Alma

URL

Ödeme almak için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.

HTTP Metod URL
POST /payment/v1/card-payments

İstek Parametreleri

Ö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

Kart Bilgileri

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.

Kredi Kartı, Debit Kart ya da Prepaid Kart Bilgileri

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ı)

Saklı Kart Bilgileri

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ı)

Sadece Sigorta Sektörüne Özel İlk 6, Son 4 ve TCKN ile Ödemede Gerekli Kart Bilgileri

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

Ödeme Kırılım Bilgileri

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

Fraud Kontrol Parametreleri

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

Ödeme Ek Parametreleri

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

Dönüş Parametreleri

Ö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 Kırılımı Dönüş Bilgileri

Ö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

Ödeme Kırılımı Para Gönderim Dağılımı

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

Ödeme Sonucu Ek Bilgiler

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.

Üye işyeri POS bilgileri

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

Örnek Kodlar

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