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