Merge pull request #73 from ibrahimgunduz34/b15011201

Döküman oluşturulması.
paranoiaproject · Jan 12, 2015 · 362fad5 · 362fad5
2 parents 162a0b8 + a50da93
commit 362fad5
Show file tree

Hide file tree

Showing 11 changed files with 296 additions and 148 deletions.
diff --git a/README.md b/README.md
@@ -1,150 +1,8 @@
-# Paranoia
+# Paranoia Nedir ?
+Paranoia, Türkiye genelinde sanal pos servisi veren banka ve ödeme servisi sağlayıcıların apilerini ortak bir arayüz üzerinden basitce kullanılabilmesini sağlayarak geliştirme maliyetlerini aşağıya çekmeyi hedefleyen açık kaynaklı bir PHP kütüphanesidir.
 
-[![Build Status](https://travis-ci.org/ParanoiaProject/paranoia.svg?branch=master)](https://travis-ci.org/ibrahimgunduz34/paranoia)
+# Neler Yapılabilir ?
+Paranoia, senkron çalışan kartlı ödeme sistemleri üzerinden peşin ve taksitli olmak üzere ön satış onayı (pre authorization), satışa dönüştürme (post authorization), satış (sale), iade (refund) ve iptal (cancel) işlemlerini gerçekleştirebilmektedir.
 
-## Nedir ?
-Paranoia, Türkiye dahilinde kullanılan popüler ödeme sistemlerinin tek bir API arayüzü üzerinden basitce kullanımına olanak veren açık kaynak kodlu bir kütüphanedir.
-
-## Nasıl çalışır ?
-Paranoia kullanarak desteklenen senkron ve asenkron ödeme servisleri üzerinden kolayca satış, iptal ve iade işlemlerinizi gerçekleştirebilirsiniz.
-
-## Kullanım:
-
-Repoyu kopyaladıktan sonra composer ile paranoia kurulumunu gerceklestirebilirsiniz.
-```shell
-	$ composer install
-```
-
-### Örnek Satış İşlemi:
-
-```php
-<?php
-require "vendor/autoload.php";
-
-use Paranoia\Payment\Factory;
-use Paranoia\Payment\Request;
-use Paranoia\Communication\Exception\CommunicationFailed;
-use Paranoia\Payment\Exception\UnexpectedResponse;
-// Iletisim sirasinda gonderilen ve alinan verileri dinlemek icin asagidaki
-// satir(lar)da yeralan yorum isaretlerini kaldiriniz.
-// use Paranoia\EventManager\Listener\CommunicationListener;
-
-$config  = json_decode(file_get_contents('tests/Resources/config/config.json'));
-
-$adapter = Factory::createInstance($config, 'estbank');
-
-// Iletisim sirasinda gonderilen ve alinan verileri dinlemek icin asagidaki
-// satir(lar)da yeralan yorum isaretlerini kaldiriniz.
-// $listener = new CommunicationListener();
-// $adapter->getConnector()->addListener('BeforeRequest', $listener);
-// $adapter->getConnector()->addListener('AfterRequest', $listener);
-
-$request = new Request();
-$request->setCardNumber('5406675406675403')
-        ->setSecurityCode('000')
-        ->setExpireMonth(12)
-        ->setExpireYear(2015)
-        ->setOrderId('ORDER000000' . time())
-        ->setAmount(100.35)
-        ->setCurrency('TRY');
-
-try {
-    $response = $adapter->sale($request);
-    if($response->isSuccess()) {
-        print "Odeme basariyla gerceklestirildi." . PHP_EOL;
-    } else {
-        print "Odeme basarisiz." . PHP_EOL;
-    }
-} catch(CommunicationFailed $e) {
-    print "Baglanti saglanamadi." . PHP_EOL;
-} catch(UnexpectedResponse $e) {
-    print "Banka beklenmedik bir cevap dondu." . PHP_EOL;
-} catch(Exception $e) {
-    print "Beklenmeyen bir hata olustu." . PHP_EOL;
-}
-```
-
-## Desteklenen Ödeme Sistemleri:
-
-* ***Est***
-	* İşbankası, Akbank, Finansbank, Denizbank, Kuveytturk, Halkbank, Anadolubank, ING Bank, Citibank, Cardplus
-* ***Gvp***
-	* Denizbank, TEB, ING, Şekerbank, TFKB, Garanti
-* ***Posnet***
-	* Yapı Kredi, Vakıfbank, Anadolubank - ***Yakında***
-* ***BKM Express***
-	* ***Yakında***
-* ***Turkcell Cüzdan***
-	* ***Yakında***
-* ***PayPal***
-	* ***Yakında***
-* ***Ininal***
-	* ***Yakında***
-
-## Desteklenen Para Birimleri:
-
-* ***TRL:*** Türk Lirası
-* ***EUR:*** Avro
-* ***USD:*** Amerikan Doları
-
-## Katkıda Bulunun:
-Siz de yapacağınız geliştirmelerle açık kaynaklı Paranoia kütüphanesine katkıda bulunabilirsiniz.
-
-Katkıda bulunmak için aşağıdaki işlem adımlarını gerçekleştirin:
-
-### Hazırlık:
-
-* ***[email protected]:paranoiaproject/paranoia.git*** deposunu kendi github hesabınıza fork edin.
-* Kendi hesabınızdaki fork edilmiş repoyu yerel geliştirme ortamınıza kopyalayın.
-
-```sh
-
-$ git clone [email protected]:youruser/paranoia.github
-
-```
-* ***[email protected]:paranoiaproject/paranoia.git*** reposunu yerel geliştirme ortamınıza upstream olarak tanımlayın.
-
-```sh
-
-$ git remote add upstream https://github.com/paranoiaproject/paranoia
-
-```
-
-### Değişikliklerin/Geliştirmelerin İletilmesi:
-
-* Projenin issues bölümünden dilediğiniz bir konuyu seçin veya yeni bir konu yaratın.
-* Geliştirmeye başlamadan önce upstreamdeki değişiklikleri yerel deponuza alın.
-
-```sh
-
-$ git checkout master
-$ git fetch upstream
-$ git merge upstream/master
-
-```
-
-* Yeni bir dal oluşturun ve giriş yapın.
-
-```sh
-
-$ git checkout -b <branch-adi-issueid>
-
-```
-
-* Değişikliklerinizi tamamlayın ve yerel deponuza gönderin.
-
-```sh
-
-$ git add .
-$ git commit -m "#<issueid> Geliştirme hakkında kısa bir commit mesajı."
-
-```
-
-* Yerel depodaki değişimi fork ettiğiniz depoya iletin.
-
-```sh
-
-$ git push origin <yourbranchname-issueid>
-
-```
-* Son olarak değişiklikleri bildirmek için bize bir ***pull request*** gönderin.
+# Nasıl Kullanılır ?
+Paranoia kütüphanesinin kurulum ve kullanımı ile ilgili olarak [dökümanlar](/docs/icindekiler.md)ı inceleyebilirsiniz.
diff --git a/docs/1-genel-baks.md b/docs/1-genel-baks.md
@@ -0,0 +1,6 @@
+# 1. Genel Bakış
+Paranoia, Türkiye genelinde sanal pos hizmeti veren bankaların ve ödeme servisi sağlayıcılarının API lerini tek bir arayüz üzerinden kullanmanızı sağlayarak zaman ve geliştirme maliyetlerinizi aşağıya çekmeyi amaçlayan açık kaynaklı bir PHP kütüphanesidir. 
+
+Paranoia, her hareket tipi için harket tipine uygun belirli parametrelerle doldurulmuş bir istek objesinin, ilgili hareketi icra eden metoda argüman olarak gönderilmesi, ve ödeme tipi ne olursa olsun hareketin sonucu/başarı durumu ve hareketle ilgili diğer detayları dönen standart bir yanıt objesinin dönmesi şeklinde çalışır.
+
+[İçindekiler sayfasına dön](/docs/icindekiler.md)
diff --git a/docs/2-desteklenen-odeme-sistemleri.md b/docs/2-desteklenen-odeme-sistemleri.md
@@ -0,0 +1,12 @@
+# 2. Desteklenen Ödeme Sistemleri
+
+| Ödeme Sistemi | Ödeme Tipi | Desteklenen Kur Tipleri | Açıklama                      |
+|---------------|------------|-------------------------|-----|
+| Est           | Non-3d     | TRY, EUR, USD | İş Bankası, Akbank, Finansbank, Denizbank, Kuveytturk, Halkbank, Anadolubank, ING Bank, Citibank, Cardplus bankaları tarafından sağlanan kredi kartları ile işlem yapılabilir. |
+| Posnet        | Non-3d     | TRY, EUR, USD | Yapı Kredi, Vakıfbank, Anadolubank bankaları tarafından sağlanan kredi kartları ile işlem yapılabilir. |
+| Gvp | Non-3d | TRY, EUR, USD | Denizbank, TEB, ING, Şekerbank, TFKB, Garanti bankaları tarafından sağlanan kredi kartları ile işlem yapılabilir. |
+
+
+**Not:** Türkiye'de debit kart ile internet alışverişlerine izin veren bazı bankalar 3D secure olmaksızın işlem ypaılabilmesine olanak vermemektedir. Paranoia, bu sürümünde yalnızca Non-3d işlemleri desteklediğinden desteklenen bazı ödeme sistemleri veya belirli bankalarda debit kart (banka kartı) ile işlem gerçekleştirelemeyebilir.
+
+[İçindekiler sayfasına dön](/docs/icindekiler.md)
diff --git a/docs/3-islemler.md b/docs/3-islemler.md
@@ -0,0 +1,9 @@
+# 3. İşlemler
+
+* [3.1. Satış İşlemi](/docs/31-sats-islemi.md)
+* 3.2. Ön Onaylı Sipariş İşemi
+* 3.3. Ön Onaylı Sipariş İşleminin Satış İşlemine Dönüştürülmesi
+* [3.4. İptal İşlemi](/docs/34-iptal-islemi.md)
+* [3.5. İade İşlemi](/docs/35-iade-islemi.md)
+
+[İçindekiler sayfasına dön](/docs/icindekiler.md)
diff --git a/docs/31-sats-islemi.md b/docs/31-sats-islemi.md
@@ -0,0 +1,96 @@
+# 3.1. Satış İşlemi
+
+## 3.1.1. Genel Bakış
+
+Satış işlemi, müşterinin ödeme aracı bilgilerinin (Kredi kartı vb.) ilgili ödeme sistemi sağlayıcısının sistemine iletilip müşteri hesabının borçlandırılması şeklinde gerçekleştirilir. 
+
+## 3.1.2. Satış İsteği Oluşturma
+
+Satış isteği, **Paranoia\Payment\Request**  tipinde bir nesnenin sipariş ve ödeme aracı (kredi kartı vb.) bilgileri ile doldurulması suretiyle elde edilir.
+
+```php
+$request = new \Paranoia\Payment\Request();
+$request->setCardNumber('5406******675403')
+        ->setSecurityCode('000')
+        ->setExpireMonth(12)
+        ->setExpireYear(2015)
+        ->setOrderId('ORDER000000' . time())
+        ->setAmount(100.35)
+        ->setCurrency('TRY');
+```        
+
+## 3.1.3. Satış İsteği Sırasında Beklenen Parametreler
+
+| Parametre | Tip | Zorunluluk | Açıklama |
+| ----------| ---- | -------------- | -------------------- |
+| CardNumber | Numeric | Evet | Kart Numarası |
+| SecurityCode | Numeric | Evet | Kartın arka yüzünde yazan güvenlik numarası |
+| ExpireMonth | Numeric | Evet | Kartın son kullanma tarihinin ay bölümü. |
+| ExpireYear | Numeric | Evet | Kartın son kullanma tarihinin 4 haneli yıl bölümü |
+| OrderId | String | Hayır | Sipariş numarası. Gönderilmediği durumlarda desteklenen sağlayıcılar tarafından oluşturularak otomatik olarak işlem yanıtında döner. |
+| Amount | Decimal | Evet | Sipariş Tutarı Format: ###.## |
+| Currency | String | Evet | 3 Haneli para birimi kodu. TRY, EUR veya USD değerlerinden birini alabilir. |
+
+## 3.1.4. Satış İşleminin Gerçekleştirilmesi.
+
+* Satış işlemi için yeni bir sipariş isteği oluşturuyoruz.
+```php
+$request = new \Paranoia\Payment\Request();
+$request->setCardNumber('5406******675403')
+        ->setSecurityCode('000')
+        ->setExpireMonth(12)
+        ->setExpireYear(2015)
+        ->setOrderId('ORDER000000' . time())
+        ->setAmount(100.35)
+        ->setCurrency('TRY');
+```
+
+* Sağlayıcı API'sine bağlantı kurmak için gerekli konfigürasyon bilgilerini dolduruyoruz. Konfigürasyon parametreleri, ödeme sistemi sağlayıcısına göre değişkenlik göstermektedir. Ödeme sağlayıcılarına göre gerekli konfigürasyon tanımlamaları hakkında daha fazla bilgi edinmek için [bu bölümü]() inceleyiniz.
+```php
+$configuration = new \Paranoia\Configuration\Est();
+$configuration->setClientId('123456789')
+        ->setUsername('API_USERNAME')
+        ->setPassword('API_PASSWORD')
+        ->setMode('P');
+
+```
+
+* Satış işlemini gerçekleştiriyoruz. Sağlayıcı uyarlamaları, Sağlayıcının [2. Desteklenen Ödeme Sistemleri](/docs/2-desteklenen-odeme-sistemleri.md) dökümanında belirtilen **ödeme sistemi** nin adı ile adlandırılmışlardır. Örnekte belirtilen Est uyarlaması için \Paranoia\Payment\Adapter\**Est** sınıfını kullanabildiğiniz gibi Posnet uyarlaması için **\Paranoia\Payment\Adapter\**Posnet** sınıfını kullanabilirsiniz.
+```php
+try {
+        $adapter = new \Paranoia\Payment\Adapter\Est(configuration);
+        $response = $adapter->sale($request);
+} catch(\Paranoia\Communication\Exception\CommunicationFailed $e) {
+         // Bağlantı hatası durumunda yapılacak işlemleri
+         // bu bölümde greçekleştirebilirsiniz.
+} catch(\Paranoia\Communication\Exception\UnexpectedResponse $e) {
+        // Ödeme sistemi sağlayıcısından beklenmedik bir yanıt
+        // dönmesi (boş yanıt veya beklenmedik bir hata mesajı gibi)
+        // durumunda yapılacak işlemleri bu bölümde gerçekleştirebilirsiniz.
+} catch(\Exception $e) {
+        // Uygulamada beklenmedik bir hata meydana gelmesi durumunda
+        // yapılacak işlemleri bu bölümde gerçekleştirebilirsiniz.
+}
+
+if($response->isSuccess()) {
+        // ödeme işlemi başarılı olduğu durumda yapılacak
+        // işlemleri bu bölümde gerçekleştirebilirsiniz.
+} else {
+        // ödeme işlemi başarısız olduğu durumda yapılacak
+        // işlemleri bu bölümde gerçekleştirebilirsiniz.
+}
+```
+
+* Ödeme işlemi başarılı olduğu takdirde, işleme ait transaction numarası saklanmalıdır. Transaction numarası işlem iptali gerektiği durumlarda kullanılacaktır.
+```php
+$transactionId = $response->getTransactionId();
+//...
+```
+
+* İşlem başarısız olduğu durumda hatanın nedeni ve hata koduna ait bilgilere aşağıdaki gibi ulaşabilirsiniz.
+```php
+$code = $response->getResponseCode();
+$message = $response->getResponseMessage();
+```
+
+* [3. İşlemler sayfasına dön](/docs/3-islemler.md)
diff --git a/docs/32-on-onayl-siparis-isemi.md b/docs/32-on-onayl-siparis-isemi.md
@@ -0,0 +1 @@
+Döküman, henüz yazım aşamasında.
diff --git a/docs/33-on-onayl-siparis-isleminin-sats-islemine-donusturulmesi.md b/docs/33-on-onayl-siparis-isleminin-sats-islemine-donusturulmesi.md
@@ -0,0 +1 @@
+Döküman, henüz yazım aşamasında.
diff --git a/docs/34-iptal-islemi.md b/docs/34-iptal-islemi.md
@@ -0,0 +1,82 @@
+# 3.4. İptal İşlemi
+
+## 3.4.1. Genel Bakış
+
+İptal işlemi, gerçekleştirilen ödeme işleminin iptal edilmesidir. Yalnızca ödeme ile aynı gün içerisinde gerçekleştirilebilir. Ödeme işleminden sonraki günlerde paranın tekrar müşteriye iade edilmesi için iade işleminin gerçekleştirilmesi gerekmektedir. Konuyla ilgili dökümana [buradan](/docs/35-iade-islemi.md) ulaşabilirsiniz.
+
+## 3.4.2. İptal İsteği Oluşturma
+
+İptal isteği, **Paranoia\Payment\Request**  tipinde bir nesnenin transaction numarası ile doldurulması suretiyle elde edilir.
+
+```php
+$request = new \Paranoia\Payment\Request();
+$request->setTransactionId('1234567890');
+```
+
+İptal işlemi sipariş numarası ile de gerçekleştirilebilmektedir.<br />
+**Not:** Bu kullanım şekli bazı bankalar tarafından tavsiye edilmemektedir.
+```php
+$request = new \Paranoia\Payment\Request();
+$request->setOrderId('987654321');
+```
+
+
+## 3.4.3. İptal İsteği Sırasında Beklenen Parametreler
+
+| Parametre | Tip | Zorunluluk | Açıklama |
+| ----------| ---- | -------------- | -------------------- |
+| TransactionId | String | Evet**\*** | Banka tarafından ödeme hareketi için gönderilmiş olan transaction numarası. |
+| OrderId | String | Evet**\*** | Banka veya sizin tarafınızdan belirlenmiş olan sipariş numarası |
+**\* **: İşlem sırasında transaction numarası veya sipariş numarasından yalnızca bir tanesi kullanılabilir.
+
+## 3.4.4. İptal İşleminin Gerçekleştirilmesi.
+
+* İptal işlemi için yeni bir iptal isteği oluşturuyoruz.
+```php
+$request = new \Paranoia\Payment\Request();
+$request->setTransactionId('1234567890');
+```
+
+* Sağlayıcı API'sine bağlantı kurmak için gerekli konfigürasyon bilgilerini dolduruyoruz. Konfigürasyon parametreleri, ödeme sistemi sağlayıcısına göre değişkenlik göstermektedir. Ödeme sağlayıcılarına göre gerekli konfigürasyon tanımlamaları hakkında daha fazla bilgi edinmek için [bu bölümü]() inceleyiniz.
+```php
+$configuration = new \Paranoia\Configuration\Est();
+$configuration->setClientId('123456789')
+        ->setUsername('API_USERNAME')
+        ->setPassword('API_PASSWORD')
+        ->setMode('P');
+
+```
+
+* İptal işlemini gerçekleştiriyoruz. Sağlayıcı uyarlamaları, Sağlayıcının [2. Desteklenen Ödeme Sistemleri](/docs/2-desteklenen-odeme-sistemleri.md) dökümanında belirtilen **ödeme sistemi** nin adı ile adlandırılmışlardır. Örnekte belirtilen Est uyarlaması için \Paranoia\Payment\Adapter\**Est** sınıfını kullanabildiğiniz gibi Posnet uyarlaması için **\Paranoia\Payment\Adapter\**Posnet** sınıfını kullanabilirsiniz.
+```php
+try {
+        $adapter = new \Paranoia\Payment\Adapter\Est(configuration);
+        $response = $adapter->cancel($request);
+} catch(\Paranoia\Communication\Exception\CommunicationFailed $e) {
+         // Bağlantı hatası durumunda yapılacak işlemleri
+         // bu bölümde greçekleştirebilirsiniz.
+} catch(\Paranoia\Communication\Exception\UnexpectedResponse $e) {
+        // Ödeme sistemi sağlayıcısından beklenmedik bir yanıt
+        // dönmesi (boş yanıt veya beklenmedik bir hata mesajı gibi)
+        // durumunda yapılacak işlemleri bu bölümde gerçekleştirebilirsiniz.
+} catch(\Exception $e) {
+        // Uygulamada beklenmedik bir hata meydana gelmesi durumunda
+        // yapılacak işlemleri bu bölümde gerçekleştirebilirsiniz.
+}
+
+if($response->isSuccess()) {
+        // İptal işlemi başarılı olduğu durumda yapılacak
+        // işlemleri bu bölümde gerçekleştirebilirsiniz.
+} else {
+        // İptal işlemi başarısız olduğu durumda yapılacak
+        // işlemleri bu bölümde gerçekleştirebilirsiniz.
+}
+```
+
+* İşlem başarısız olduğu durumda hatanın nedeni ve hata koduna ait bilgilere aşağıdaki gibi ulaşabilirsiniz.
+```php
+$code = $response->getResponseCode();
+$message = $response->getResponseMessage();
+```
+
+* [3. İşlemler sayfasına dön](/docs/3-islemler.md)