BKM Express Dökümantasyonu

 BKM Express Dökümantasyonu Yazarlar: Yalçın YENİGÜN Versiyon: 1.0 iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com İçindekiler iyzico API Dökümantasyonu ....................................................................................................................................... 1 1 Başlarken ................................................................................................................................................................ 3 2 API Servisleri .......................................................................................................................................................... 4 2.1 API Servisleri, Ortak İstek (Request) ve Sonuç (Response) Alanları ...................................................................... 4 2.2 Ödeme ............................................................................................................................................................................. 5 2.2.2 İptal .............................................................................................................................................................................................. 16 2.2.3 İade .............................................................................................................................................................................................. 17 iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com 1 Başlarken iyzico ödeme API’si, internet üzerinden ödeme kabul eden tüm üye işyerlerine hitap edecek bir şekilde, oturum bilgisi tutmayan (stateless) Restful servis odaklı bir mimaride geliştirilmiştir. İletişim, şifreleme (PKI: public key infrastructure), veri sarmalama (data marshalling) ve veri çözme (data unmarshalling) için mutlaka bir API istemcisi (client) kullanmak gerekir. İyzico; • Java • .Net • PHP • Ruby on Rails (RoR) • Phyton dillerinde yazılmış API istemcileri sunar. Üye işyeri kendi programlama diline göre uygun API istemcisini seçmelidir. İyzico API entegrasyonu için temelde 3 bilgiye ihtiyaç vardır: • API Base URL : Ortam (sandbox/canlı) bazlı API servis ana linkidir. Örnek: https://stg.iyzipay.com • API Key : Üye işyeri açık API anahtarıdır. Bu anahtar iyzico ile iletişimde kullanılır fakat kimseyle paylaşılmaz. Örnek: Txl2ctiktW6BrNmFo10pZiPn8W67Ksob • Secret Key : Üye işyeri gizli API güvenlik anahtarıdır. Bu anahtar iyzico ile iletişimde kullanılmaz ve kimseyle paylaşılmaz. Örnek: GdzIHrXly6gQkZfEZUEw0LqbXFq7NWOg3qB3cPAHgx9DmXGcQlZIF4XelwC0kBD3 iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com 2 API Servisleri iyzico API dahilinde BKM Express için geliştirilen servisler aşağıdadır. Üye işyeri ile paylaşılan API istemcisi bu API servislerine istekte bulunmakta ve veri alışverişini, şifrelemeyi ve güvenliği üye işyeri adına basitçe halletmektedir. # 1 2 3 4 API Servis (Endpoint) İsmi BKM Express Ödeme Başlatma Servisi (initializeBKM) BKM Express Ödeme Sorgulama Servisi (getBKMAuthResponse) Ödeme iade servisi Ödeme iptal servisi API Servis (Endpoint) URL /payment/iyzipos/bkm/initialize Method POST POST /payment/iyzipos/bkm/auth/detail /payment/iyzipos/refund /payment/iyzipos/cancel POST POST 2.1 API Servisleri, Ortak İstek (Request) ve Sonuç (Response) Alanları API servislerine mutlaka iyzico istemcileri (client) ile erişim sağlanması gerekmektedir, zira iyzico istemcileri sizin adınıza yetkilendirme ve veri gönderip almayı kolaylaştırır. Yapılan tüm servis isteklerinde; • Request Header’ın içinde Authorization ve x-­‐iyzi-­‐rnd parametreleri bulunmalıdır. İyzico istemcileri bunu sizin adınıza halleder. • Aşağıdaki istek parametreleri opsiyonel olarak gönderilebilir: Input İsmi Veri Tipi Zorunlu Açıklama locale String Hayır conversationId String Hayır iyzico istek snucunda dönen metinlerin dilini ayarlamak için kullanılır. Varsayılan değeri tr’dir. İstek esnasında gönderip, sonuçta alabileceğiniz bir değer, request/response eşmesi yapmak için kullanılabilir • Aşağıdaki sonuç parametreleri dönülür. Sonuç (status) başarılı (success) ise yapılan isteğe özel diğer alanlar dolu gelecektir: Output İsmi Veri Tipi status String errorCode String errorMessage String Açıklama Yapılan isteğin sonucunu bildirir. İşlem başarılı ise success, hatalı ise failure döner İşlem hatalıysa, bu hataya dair belirtilen koddur İşlem hatalıysa, bu hataya dair belirtilen mesajdır, locale iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com errorGroup String locale String conversationId String systemTime Long parametresine göre dil desteği sunar İşlem hatalıysa, bu hataya dair belirtilen gruptur İstekte belirtilen locale değeri geri dönülür, varsayılan değeri tr’dir İstek esnasında gönderilmişse, sonuçta aynen geri iletilir Dönen sonucun o anki unix timestamp değeridir 2.2 Ödeme Üye işyeri BKM Express ile aşağıda belirtilen parametre değerleri ile ödeme alabilir. 2.2.1 Ödeme İstek ve Dönüş Parametreleri Veri Sözlüğü
Tüm ödemeler için aşağıdaki tabloda yer alan input parametreleri geçerlidir. Input İsmi Veri Tipi Zorunlu Açıklama Hayır ** BKM Express ödeme akışında üye işyerine başarılı ve hatalı sonucu bildirmek üzere alınan URL adresi. Sadece BKM Express ile ödemenin initializeBKM metodunda zorunludur. Token String Evet BKM Express’in işleme özel ürettiği değer. Price Decimal basketId String Evet Hayır Hayır Ödeme sepet tutarı. Üye işyeri sepet id’si Ödeme grubu, varsayılan PRODUCT. Geçerli değerler enum içinde sunulmaktadır: PRODUCT, LISTING, SUBSCRIPTION id (Buyer) String Evet Üye işyeri tarafındaki alıcıya ait id name (Buyer) String Evet Üye işyeri tarafındaki alıcıya ait ad surname (Buyer) String Evet email (Buyer) String Evet Üye işyeri tarafındaki alıcıya ait soyad Üye işyeri tarafındaki alıcıya ait e-­posta bilgisi. E-­posta adresi alıcıya ait geçerli ve erişilebilir bir adres olmalıdır ip (Buyer) String Evet Üye işyeri tarafındaki alıcıya ait IP adresi identityNumber (Buyer) String Evet Üye işyeri tarafındaki alıcıya ait kimlik (TCKN) numarası city (Buyer) String Evet Üye işyeri tarafındaki alıcıya ait şehir bilgisi country (Buyer) String Evet Üye işyeri tarafındaki alıcıya ait ülke bilgisi gsmNumber (Buyer) String registrationAddress (Buyer) String Hayır Üye işyeri tarafındaki alıcıya ait GSM numarası Evet Üye işyeri tarafındaki alıcıya ait kayıt adresi zipCode (Buyer) String Hayır registrationDate (Buyer) String Hayır lastLoginDate (Buyer) String contactName (BillingAddress) String Hayır Üye işyeri tarafındaki alıcıya ait posta kodu Üye işyeri tarafındaki alıcıya ait kayıt tarihi. Tarih formatı 2015-­09-­17 23:45:06 şeklinde olmalıdır Üye işyeri tarafındaki alıcıya ait son giriş tarihi. Tarih formatı 2015-­09-­
17 23:45:06 şeklinde olmalıdır Evet Üye işyeri tarafındaki fatura adresi ad soyad bilgisi callbackUrl String paymentGroup String iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com city (BillingAddress) country (BillingAddress) address (BillingAddress) zipCode (BillingAddress) String Evet Üye işyeri tarafındaki fatura adresi şehir bilgisi String Evet Üye işyeri tarafındaki fatura adresi ülke bilgisi String Evet Üye işyeri tarafındaki fatura adresi String Hayır String Evet ** Evet ** Üye işyeri tarafındaki fatura adresi posta kodu Üye işyeri tarafındaki teslimat adresi ad soyad bilgisi. Sepetteki ürünlerden en az 1 tanesi fiziksel ürün (itemType=PHYSICAL) ise zorunludur Üye işyeri tarafındaki teslimat adresi şehir bilgisi. Sepetteki ürünlerden en az 1 tanesi fiziksel ürün (itemType=PHYSICAL) ise zorunludur Üye işyeri tarafındaki teslimat adresi ülke bilgisi. Sepetteki ürünlerden en az 1 tanesi fiziksel ürün (itemType=PHYSICAL) ise zorunludur Üye işyeri tarafındaki teslimat adresi. Sepetteki ürünlerden en az 1 tanesi fiziksel ürün (itemType=PHYSICAL) ise zorunludur Hayır Üye işyeri tarafındaki teslimat adresi posta kodu Evet Evet Üye işyeri tarafındaki sepetteki ürüne ait id Üye işyeri tarafındaki sepetteki ürüne ait tip. Geçerli enum değerler: PHYSICAL ve VIRTUAL Evet Üye işyeri tarafındaki sepetteki ürüne ait isim Evet Üye işyeri tarafındaki sepetteki ürüne ait kategori 1 Hayır Üye işyeri tarafındaki sepetteki ürüne ait kategori 2 Üye işyeri tarafındaki sepetteki ürüne ait tutar. 0 ve 0’dan küçük olamaz, tutarlar toplamı sepet tutarına (price) eşit olmalıdır Üye işyeri tarafındaki sepetteki ürüne istinaden alt üye işyerine gönderilecek olan tutar. 0’dan küçük ve sepet ürün tutarından [price (BasketItem)] büyük olamaz Pazaryeri iş modeli için geçerli ve zorunludur Üye işyeri tarafındaki sepetteki ürüne istinaden alt üye işyerine ait anahtar. Pazaryeri iş modeli için geçerli ve zorunludur contactName (ShippingAddress) city (ShippingAddress) String country (ShippingAddress) String address (ShippingAddress) String zipCode (ShippingAddress) String id (BasketItem) String itemType (BasketItem) String name (BasketItem) String category1 (BasketItem) String category2 (BasketItem) String price (BasketItem) Decimal subMerchantPrice (BasketItem) Evet ** Decimal subMerchantKey (BasketItem) String Evet ** Evet ** Evet Evet ** Output İsmi Veri Tipi Açıklama paymentId String price Decimal paidPrice Decimal installment Integer Token String callbackUrl String paymentStatus String binNumber String cardAssociation String cardFamily String Ödemeye ait id, üye işyeri tarafından mutlaka saklanmalıdır. Ödemenin iptali ve iyzico ile iletişimde kullanılır Ödeme sepet tutarı. Kırılım tutarlar toplamı sepet tutarına eşit olmalı İndirim vade farkı vs hesaplanmış POS’dan geçen, tahsil edilen, nihai tutar Ödemenin taksit bilgisi, tek çekim için 1 döner. BKM Express’in işleme özel ürettiği değer. BKM Express ödeme akışında üye işyerine başarılı ve hatalı sonucu bildirmek üzere alınan URL adresi. Sadece BKM Express ile ödemenin initializeBKM metodunda zorunludur. İşlemin sonucunu gösterir. Ödeme yapılan kartın ilk 6 hanesi Eğer ödeme yapılan kart yerel bir kart ise, kartın ait olduğu kuruluş. Geçerli değerler: VISA, MASTER_CARD, AMERICAN_EXPRESS Eğer ödeme yapılan kart yerel bir kart ise, kartın ait olduğu aile. Geçerli iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com iyziCommissionFee Decimal merchantCommissionRate Decimal merchantCommissionRateAmount Decimal paymentTransactionId (ItemTransactions) String değerler: Bonus, Axess, World, Maximum, Paraf, CardFinans, AsyaCard, ... Ödemeye ait iyzico işlem ücreti Üye işyerinin uyguladığı vade/komisyon oranı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon oranı %10’dur.Bilgi amaçlıdır Üye işyerinin uyguladığı vade/komisyon tutarı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon tutarı 10’dur.Bilgi amaçlıdır Ödeme kırılımına ait id, üye işyeri tarafından mutlaka saklanmalıdır. Ödeme kırılımının iadesi, onayı, onay geri çekmesi ve iyzico ile iletişimde kullanılır. Tercihen itemId ile ilişkili bir şekilde tutulmalıdır 2.2.2 BKM Express Ödeme Süreci
1. BKM Express ile Ödemeyi Başlatma (initializeBKM) : BKM Express ile ödeme alınabilmesi için iyzico’ya ödeme parametreleriyle birlikte bir geri dönüş (callback) URL’i POST edilir. Dönülen sonuç başarılı ise (status=success), dönüş içinde yer alan HTML içerik (htmlContent), tarayıcının responseBody’sine basılır, böylece kullanıcı otomatik olarak, bankanın BKM Express’in ödeme sayfasına yönlenir. Not: iyzico’dan dönen HTML içerik Base64 encoded olarak iletilir ancak iyzico istemcilerinde sizin adınıza otomatik olarak Base64 decoding işlemi yapılır, dolayısıyla siz kulanıcı dostu HTML içeriği görebilirsiniz. Örnek initializeBKM Request -­‐ Java @Test
public void shouldInitializeBKM() {
EcomPaymentServiceClient client = new
EcomPaymentServiceClientImpl(configuration);
EcomPaymentBKMInitializeRequest request = new
EcomPaymentBKMInitializeRequest();
request.setLocale(RequestLocaleType.TR.getValue());
request.setConversationId("123456789");
request.setPrice(new BigDecimal("1"));
request.setBasketId("B67832");
request.setPaymentGroup(PaymentGroupRequestType.PRODUCT.name());
request.setBuyer(prepareBuyer());
request.setShippingAddress(prepareShippingAddress());
request.setBillingAddress(prepareBillingAddress());
iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com request.setBasketItems(prepareBasketItems());
request.setCallbackUrl("https://www.merchant.com/callbackUrl");
EcomPaymentBKMInitializeResponse response = client.initializeBKM(request);
System.out.println("conversationId=" + response.getConversationId());
System.out.println("locale=" + response.getLocale());
System.out.println("status=" + response.getStatus());
System.out.println("errorCode=" + response.getErrorCode());
System.out.println("errorMessage=" + response.getErrorMessage());
System.out.println("errorGroup=" + response.getErrorGroup());
System.out.println("systemTime=" + response.getSystemTime());
System.out.println("htmlContent=" + response.getHtmlContent());
}
private EcomPaymentBuyerDto prepareBuyer() {
EcomPaymentBuyerDto buyer = new EcomPaymentBuyerDto();
buyer.setId("100");
buyer.setName("Hakan");
buyer.setSurname("Erdoğan");
buyer.setIdentityNumber("16045258606");
buyer.setEmail("[email protected]");
buyer.setGsmNumber("05553456789");
buyer.setRegistrationDate("2011-02-17 12:00:00");
buyer.setLastLoginDate("2015-04-20 12:00:00");
buyer.setRegistrationAddress("Maltepe");
buyer.setCity("Istanbul");
buyer.setCountry("Turkiye");
buyer.setZipCode("34840");
buyer.setIp("192.168.123.102");
return buyer;
}
private EcomPaymentShippingAddressDto prepareShippingAddress() {
EcomPaymentShippingAddressDto address = new
EcomPaymentShippingAddressDto();
address.setAddress("Malte Plaza No:56");
address.setZipCode("34840");
address.setContactName("Hakan");
address.setCity("Istanbul");
address.setCountry("Turkiye");
return address;
}
private EcomPaymentBillingAddressDto prepareBillingAddress() {
EcomPaymentBillingAddressDto address = new EcomPaymentBillingAddressDto();
address.setAddress("Malte Plaza No:56");
address.setZipCode("34840");
address.setContactName("Hakan");
address.setCity("Istanbul");
address.setCountry("Turkiye");
return address;
}
iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com private List<EcomPaymentBasketItemDto> prepareBasketItems() {
List<EcomPaymentBasketItemDto> paymentBasketItemDtoList = new
ArrayList<EcomPaymentBasketItemDto>();
EcomPaymentBasketItemDto firstBasketItem = new EcomPaymentBasketItemDto();
firstBasketItem.setId("BI101");
firstBasketItem.setName("ABC Marka Kolye");
firstBasketItem.setCategory1("Giyim");
firstBasketItem.setCategory2("Aksesuar");
firstBasketItem.setItemType(BasketItemRequestType.PHYSICAL.name());
firstBasketItem.setPrice(new BigDecimal("0.3"));
firstBasketItem.setSubMerchantKey("sub merchant key");
firstBasketItem.setSubMerchantPrice(new BigDecimal("0.27"));
EcomPaymentBasketItemDto secondBasketItem = new EcomPaymentBasketItemDto();
secondBasketItem.setId("BI102");
secondBasketItem.setName("XYZ Oyun Kodu");
secondBasketItem.setCategory1("Oyun");
secondBasketItem.setCategory2("Online Oyun Kodlari");
secondBasketItem.setItemType(BasketItemRequestType.VIRTUAL.name());
secondBasketItem.setPrice(new BigDecimal("0.5"));
secondBasketItem.setSubMerchantKey("sub merchant key");
secondBasketItem.setSubMerchantPrice(new BigDecimal("0.42"));
paymentBasketItemDtoList.add(firstBasketItem);
paymentBasketItemDtoList.add(secondBasketItem);
return paymentBasketItemDtoList;
}
Örnek initializeBKM Response – Java : conversationId=123456789
locale=tr
status=success
errorCode=null
errorMessage=null
errorGroup=null
systemTime=1450167036938
htmlContent=<!doctype html>
<html>
<head>
<meta charset="UTF-8"/>
<title>BKM Initializer</title>
</head>
<body>
iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com <div>
<form id="bkmHiddenForm" method="post"
action="https://preprod.bkmexpress.com.tr/BKMExpress/pub/purchase/init.bkm" >
<input type="hidden" name="t" value="d1b86e3b-8465-418c-b82adf9ca2ea4844"/>
<input type="hidden" name="ts" value="20151215-10:10:38"/>
<input type="hidden" name="s"
value="X4y75bAC7FVe6QdkfEOoxjSZm0CGyjS1ZqetR+7uPAzPOX9pBlqoIpDqLQ80nlISzCcROPOk
J+MbrIF2DkQIvIG2gsoRK7RknoOT8EsXfyOspt39VxnzhMThpAZ+2VWXSFYl2ovQuDkBsIpvhUmoqyI
/e/DKxlX8Lb36hQGCfBE="/>
<script>document.getElementById('bkmHiddenForm').submit();</script>
</form>
</div>
</body>
</html>
Örnek initializeBKM Request -­‐ JSON {
"locale": "tr",
"conversationId": "123456789",
"price": "0.8",
"basketId": "B67832",
"paymentGroup": "PRODUCT",
"buyer": {
"id": "100",
"name": "Hakan",
"surname": "Erdoğan",
"identityNumber": "16045078606",
"email": "[email protected]",
"gsmNumber": "05075941308",
"registrationDate": "2011-02-17 12:00:00",
"lastLoginDate": "2015-04-20 12:00:00",
"registrationAddress": "Maltepe",
"city": "İstanbul",
"country": "Türkiye",
"zipCode": "34840",
"ip": "192.168.123.102"
},
"shippingAddress": {
"address": "Malte Plaza No:56",
"zipCode": "34840",
"contactName": "Hakan",
"city": "İstanbul",
"country": "Türkiye"
},
"billingAddress": {
"address": "Malte Plaza No:56",
"zipCode": "34840",
iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com "contactName": "Hakan",
"city": "İstanbul",
"country": "Türkiye"
},
"basketItems": [
{
"id": "BI101",
"price": "0.3",
"name": "ABC Marka Kolye",
"category1": "Giyim",
"category2": "Aksesuar",
"itemType": "PHYSICAL",
"subMerchantKey": "sub merchant key",
"subMerchantPrice": "0.27"
},
{
"id": "BI102",
"price": "0.5",
"name": "XYZ Oyun Kodu",
"category1": "Oyun",
"category2": "Online Oyun Kodları",
"itemType": "VIRTUAL",
"subMerchantKey": "sub merchant key",
"subMerchantPrice": "0.42"
}
],
"callbackUrl": "https://www.merchant.com/callbackUrl"
}
Örnek initializeBKM Response -­‐ JSON {
"status": "success",
"locale": "tr",
"systemTime": 1450167583466,
"conversationId":"123456789",
"htmlContent":"<!doctype html>
<html>
<head>
<meta charset="UTF-8"/>
<title>BKM Initializer</title>
</head>
<body>
<div>
<form id="bkmHiddenForm" method="post"
action="https://preprod.bkmexpress.com.tr/BKMExpress/pub/purchase/init.bkm" >
<input type="hidden" name="t" value="2109c84f-ae13-4e96-afa58b1a3573ee2b"/>
<input type="hidden" name="ts" value="20151215-10:19:45"/>
<input type="hidden" name="s"
value="rjE764d7fQp+8ShxghSgmvnKYnooGN4fAxdX3A469TGHoyeJ8pQgW7gozgRne+dMmlfBinzK
0MJdfzDoGeg3YgwCGdMBwMFrikiVApphmKAHbuKley8Yoya7qXSD9RqC7JL8fpnt7x+wmab+P7nLEG2
Xn674RGeloxu4zzy28GQ="/>
iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com <script>document.getElementById('bkmHiddenForm').submit();</script>
</form>
</div>
</body>
</html>"
}
2. Üye İşyerine Dönüş (callback) : Kullanıcı BKM Express’in ödeme sayfasında kartını seçip SMS şifresini girdikten sonra, sonuç iyzico’ya gelir. İyzico kendi kontrollerini yaptıktan sonra, üye işyeri tarafında gerekli kontrollerin (ürün hala satışta mı, ürün hala stokta mı, oturum hala açık mı, vb) yapılması için üye işyerinin callback URL’ine HTML post eder. Bu aşamada kullanıcının hesabından belirtilen tutar çekilir. 3. BKM Express ile Ödemeyi Sorgulama (getBKMAuthResponse) : iyzico ödeme sürecini tamamladıktan sonra, üye işyerinin ilk adımda iyzico’ya ilettiği callbackUrl’e ödeme tokenı POST eder. Üye işyeri, kendisine post edilen tokeni kullaranarak, ödeme ile ilgili tüm detayları öğrenmek için iyzico’ya istekte (getBKMAuthResponse) bulunur ve işlemin sonucuna göre aksiyon alır. Örnek getBKMAuthResponse Request –Java : EcomPaymentServiceClient client = new
EcomPaymentServiceClientImpl(configuration);
EcomRetrievePaymentBKMAuthRequest request = new
EcomRetrievePaymentBKMAuthRequest();
request.setLocale(RequestLocaleType.TR.getValue());
request.setConversationId("123456789");
request.setToken("10bfd53e-56a9-447a-84a2-9a7d33fff224");
EcomRetrievePaymentBKMAuthResponse response =
client.getBKMAuthResponse(request);
System.out.println("conversationId=" + response.getConversationId());
System.out.println("locale=" + response.getLocale());
System.out.println("status=" + response.getStatus());
System.out.println("errorCode=" + response.getErrorCode());
System.out.println("errorMessage=" + response.getErrorMessage());
System.out.println("errorGroup=" + response.getErrorGroup());
System.out.println("systemTime=" + response.getSystemTime());
System.out.println("paymentId=" + response.getPaymentId());
System.out.println("price=" + response.getPrice());
iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com System.out.println("paidPrice=" + response.getPaidPrice());
System.out.println("installment=" + response.getInstallment());
System.out.println("basketId=" + response.getBasketId());
System.out.println("binNumber=" + response.getBinNumber());
System.out.println("cardAssociation=" + response.getCardAssociation());
System.out.println("cardFamily=" + response.getCardFamily());
System.out.println("cardType=" + response.getCardType());
System.out.println("cardToken=" + response.getCardToken());
System.out.println("cardUserKey=" + response.getCardUserKey());
System.out.println("fraudStatus=" + response.getFraudStatus());
System.out.println("iyziCommissionFee=" + response.getIyziCommissionFee());
System.out.println("iyziCommissionRateAmount=" +
response.getIyziCommissionRateAmount());
System.out.println("merchantCommissionRate=" +
response.getMerchantCommissionRate());
System.out.println("merchantCommissionRateAmount=" +
response.getMerchantCommissionRateAmount());
List<EcomPaymentItemTransactionDto> itemTransactions =
response.getItemTransactions();
if (itemTransactions != null && !itemTransactions.isEmpty()) {
for (EcomPaymentItemTransactionDto itemTransaction : itemTransactions) {
System.out.println("paymentTransactionId=" +
itemTransaction.getPaymentTransactionId());
System.out.println("itemId=" + itemTransaction.getItemId());
System.out.println("paidPrice=" + itemTransaction.getPaidPrice());
System.out.println("price=" + itemTransaction.getPrice());
System.out.println("transactionStatus=" +
itemTransaction.getTransactionStatus());
System.out.println("blockageRate=" +
itemTransaction.getBlockageRate());
System.out.println("blockageRateAmountMerchant=" +
itemTransaction.getBlockageRateAmountMerchant());
System.out.println("blockageRateAmountSubMerchant=" +
itemTransaction.getBlockageRateAmountSubMerchant());
System.out.println("blockageResolvedDate=" +
itemTransaction.getBlockageResolvedDate());
System.out.println("iyziCommissionFee=" +
itemTransaction.getIyziCommissionFee());
System.out.println("iyziCommissionRateAmount=" +
itemTransaction.getIyziCommissionRateAmount());
System.out.println("merchantCommissionRate=" +
itemTransaction.getMerchantCommissionRate());
System.out.println("merchantCommissionRateAmount=" +
itemTransaction.getMerchantCommissionRateAmount());
System.out.println("merchantPayoutAmount=" +
itemTransaction.getMerchantPayoutAmount());
System.out.println("subMerchantKey=" +
itemTransaction.getSubMerchantKey());
System.out.println("subMerchantPayoutAmount=" +
itemTransaction.getSubMerchantPayoutAmount());
System.out.println("subMerchantPayoutRate=" +
itemTransaction.getSubMerchantPayoutRate());
iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com System.out.println("subMerchantPrice=" +
itemTransaction.getSubMerchantPrice());
}
}
rnek getBKMAuthResponse Response –Java conversationId=123456789
locale=tr
status=success
errorCode=null
errorMessage=null
errorGroup=null
systemTime=1450186761320
paymentId=4670
price=1.00000000
paidPrice=1.00000000
installment=1
basketId=77
binNumber=413252
cardAssociation=VISA
cardFamily=Axess
cardType=CREDIT_CARD
cardToken=null
cardUserKey=null
fraudStatus=1
iyziCommissionFee=0.25000000
iyziCommissionRateAmount=0.02500000
merchantCommissionRate=0E-8
merchantCommissionRateAmount=0E-8
paymentTransactionId=2567
itemId=90
paidPrice=0.40000000
price=0.40000000
transactionStatus=1
iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com blockageRate=10.00000000
blockageRateAmountMerchant=0.04000000
blockageRateAmountSubMerchant=0E-8
blockageResolvedDate=2015-12-25 18:50:54
iyziCommissionFee=0.10000000
iyziCommissionRateAmount=0.01000000
merchantCommissionRate=0E-8
merchantCommissionRateAmount=0E-8
merchantPayoutAmount=0.13000000
subMerchantKey=ha3us4v5mk2652kkjk5728cc4407an
subMerchantPayoutAmount=0.12000000
subMerchantPayoutRate=30.00000000
subMerchantPrice=0.12000000
paymentTransactionId=2568
itemId=91
paidPrice=0.60000000
price=0.60000000
transactionStatus=1
blockageRate=10.00000000
blockageRateAmountMerchant=0.06000000
blockageRateAmountSubMerchant=0E-8
blockageResolvedDate=2015-12-25 18:50:54
iyziCommissionFee=0.15000000
iyziCommissionRateAmount=0.01500000
merchantCommissionRate=0E-8
merchantCommissionRateAmount=0E-8
merchantPayoutAmount=0.19500000
subMerchantKey=nm57s4v5mk2652k87g5728cc56nh23
subMerchantPayoutAmount=0.18000000
subMerchantPayoutRate=30.00000000
subMerchantPrice=0.18000000
iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com rnek getBKMAuthResponse Request –JSON {
"locale": "tr",
"conversationId":"123456789",
"token":"10bfd53e-56a9-447a-84a2-9a7d33fff224"
}
Ö rnek getBKMAuthResponse Response –JSON {
"conversationId": "123456789",
"locale": "tr",
"status": "success",
"systemTime": 1450169661204,
"paymentId": "4670",
"price": 1.00000000,
"paidPrice": 1.00000000,
"installment": 1,
"binNumber": "413252",
"cardAssociation": "VISA",
"cardFamily": "Axess",
"cardType": "CREDIT_CARD",
"iyziCommissionFee": 0.25000000,
"merchantCommissionRate": 0,
"merchantCommissionRateAmount": 0,
"token": "10bfd53e-56a9-447a-84a2-9a7d33fff224",
"paymentStatus": "SUCCESS",
"callbackUrl": "https://stg-demo.iyzipay.com/callback-bkm"
}
2.2.3 İptal İyzico üzerinden tahsil edilen bir ödeme, banka kuralları gereği aynı gün içinde (gün sonu yapılmadan) iptal (cancel) edilebilir. İptal işleminin iadeden farkı, ödeme ile aynı gün yapılabilmesi ve kart ekstresinde girdi/çıktı yaratmamasıdır. İptal yapılabilmesi için ödemeye ait id (paymentId) gönderilmesi gerekir, iptal işlemi başarılıysa iptal edilen tutar (price) servisten döner. İptal işlemi tepeden çalışır, yani ödemenin tamamını iptal eder. • API Servis (Endpoint) İsmi: /payment/iyzipos/cancel • Method: HTTP POST iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com 2.2.4 İade İyzico üzerinden tahsil edilen bir ödeme, 365 gün 7/24 iade (refund) edilebilir. İade işlemi mutlaka ekstreye yansır ve iade edilen ödeme taksitli bir işlemse, iadenin karta yansıması bankadan bankaya değişmekle beraber bir kaç günü bulabilir. İade işlemi kırılımdan çalışır, yani ödemenin bir kırlımının tamamını veya bir kısmını iade eder. 2.2.4.1 Standart İade İade yapılabilmesi için ödeme kırılımına ait id (paymentTransactionId) ve iade edilecek tutar (price) gönderilmesi gerekir, iade işlemi başarılıysa iade edilen tutar (price) servisten döner. İade edilecek tutar (price), iade edilecek ödemenin kırılımının tutarından (itemTransaction à paidPrice) ve iade edilebilir kalan tutardan küçük veya eşit olmalıdır. Bu kural sağlandığı sürece ardarda defalarca iade yapılabilir. • API Servis (Endpoint) İsmi: /payment/iyzipos/refund • Method: HTTP POST iyzico Ödeme Hizmetleri A.Ş. Nidakule Göztepe İş Merkezi Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1 Kat:19 Bağımsız 70/73 Kadıköy 34732 Telefon:+90 216 599 01 00 E-­mail: [email protected] Web: www.iyzico.com