Skip to content

Commit

Permalink
updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@nuryagdym
nuryagdym committed May 8, 2022
1 parent 6eb25e4 commit 8823b02
Show file tree
Hide file tree
Showing 2 changed files with 91 additions and 22 deletions.
58 changes: 36 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Bu paket ile amaçlanan; ortak bir arayüz sınıfı ile, tüm Türk banka sanal pos sistemlerinin kullanılabilmesidir.

- **EST POS** altyapısı tam olarak test edilmiş ve kullanıma hazırdır. Akbank, TEB ve Ziraat bankası test edilmiştir.
- **EST POS** (Asseco) altyapısı tam olarak test edilmiş ve kullanıma hazırdır. Akbank, TEB ve Ziraat bankası test edilmiştir.

- **Garanti Virtual POS** ödeme sistemi çalışmaktadır, fakat 3D ödeme kısmının üretim ortamında test edilmesi gerekiyor.

Expand All @@ -16,6 +16,17 @@ Bu paket ile amaçlanan; ortak bir arayüz sınıfı ile, tüm Türk banka sanal

- **Kuveyt POS** 3d secure ödeme desteği eklenmiştir, test edildikçe, sorunları bulundukça hatalar giderilecek.

### Ana başlıklar
- [Özellikler](#zellikler)
- [Latest updates](#latest-updates)
- [Minimum Gereksinimler](#minimum-gereksinimler)
- [Kurulum](#kurulum)
- [Farklı Banka Sanal Poslarını Eklemek](#farkl-gatewayler-tek-ilem-ak)
- [Örnek Kodlar](#rnek-kodlar)
- [Troubleshoots](#troubleshoots)
- [Genel Kültür](#genel-kltr)
- [Docker ile test ortamı](#docker-ile-test-ortam)

### Özellikler
- Standart E-Commerce modeliyle ödeme (`AbstractGateway::MODEL_NON_SECURE`)
- 3D Secure modeliyle ödeme (`AbstractGateway::MODEL_3D_SECURE`)
Expand All @@ -27,7 +38,7 @@ Bu paket ile amaçlanan; ortak bir arayüz sınıfı ile, tüm Türk banka sanal
- Sipariş iptal etme (`AbstractGateway::TX_CANCEL`)

#### Farklı Gateway'ler Tek işlem akışı
* Farklı bankaya geçiş yapmak için sadece doğru `AccountFactory` method'u kullanarak account degistirmek.
* Farklı bankaya geçiş yapmak için sadece doğru `AccountFactory` method'u kullanarak account degistirmek yeterli.
* **3D**, **3DPay**, **3DHost** ödemeler arasında geçiş yapmak için tek yapmanız gereken Account konfigurasyonunda account tipini değiştirmek (`AbstractGateway::MODEL_3D_PAY` vs.). İşlem akışı aynı olduğu için kod değiştirmenize gerek kalmıyor.
* Aynı tip işlem için farklı POS Gateway'lerden dönen değerler aynı formata normalize edilmiş durumda. Yani kod güncellemenize gerek yok.
* Aynı tip işlem için farklı Gateway gönderilecek değerler de genel olarak aynı formatta olacak şekilde normalize edişmiştir.
Expand Down Expand Up @@ -67,12 +78,12 @@ require './vendor/autoload.php';
// API kullanıcı bilgileri
$account = \Mews\Pos\Factory\AccountFactory::createEstPosAccount(
'akbank', //pos config'deki ayarın index name'i
'XXXXXXX',
'XXXXXXX',
'XXXXXXX',
AbstractGateway::MODEL_3D_SECURE,
'XXXXXXX',
\Mews\Pos\Gateways\EstPos::LANG_TR
'yourClientID',
'yourKullaniciAdi',
'yourSifre',
AbstractGateway::MODEL_3D_SECURE, //storetype
'yourStoreKey',
AbstractGateway::LANG_TR
);

// API kullanıcı hesabı ile paket bir değişkene aktarılıyor
Expand All @@ -95,8 +106,8 @@ require 'config.php';
$order = [
'id' => 'BENZERSIZ-SIPERIS-ID',
'amount' => 1.01,
'currency' => 'TRY', //TRY|USD|EUR
'installment' => 0, //0 ya da 1'den büyük değer
'currency' => 'TRY', //TRY|USD|EUR, optional. default: TRY
'installment' => 0, //0 ya da 1'den büyük değer, optional. default: 0

//MODEL_3D_SECURE, MODEL_3D_PAY, MODEL_3D_HOST odemeler icin zorunlu
//Success ve Fail URL'ler farklı olabilir ama kütüphane success ve fail için aynı kod çalıştırır.
Expand All @@ -111,7 +122,7 @@ $order = [
'rand' => md5(uniqid(time())), // EstPos, Garanti, PayFor, InterPos, VakifBank. Rastegele değer.

//lang degeri verilmezse account (EstPosAccount) dili kullanılacak
'lang' => 'tr', //tr|en. Kullanıcının yönlendirileceği banka gateway sayfasının ve gateway'den dönen mesajların dili.
'lang' => AbstractGateway::LANG_TR, //LANG_TR|LANG_EN. Kullanıcının yönlendirileceği banka gateway sayfasının ve gateway'den dönen mesajların dili.
];
$session->set('order', $order);

Expand Down Expand Up @@ -233,37 +244,40 @@ Fakat,


## Troubleshoots
### session sıfırlanması
### Session sıfırlanması
Cookie session kullanığınızda, kullanıcı gatewayden geri websitenize yönlendirilidiğinde session'nin sıfırlanabilir.
Bu durumda PHP header'de `samesite=None` set etmeyi deneyin. Bu header'ı set ettikten sonra,
taraycıda yeni session oluşturun, çünkü bu değişiklik var olan session'i etkilemez.


## NonSecure, 3D, 3DPay ve 3DHost ödeme modeller arasındaki farklar
- **3D** - Gateway'den (3D şifre girdiginiz sayfadan) döndükten sonra ödemeyi tamamlamak için banka gateway'ne 1 istek daha (_provizyon_ isteği) gönderir.
###Shared hosting'lerde IP tanımsız hatası
Shared hosting'lerde Cpanel'de gördüğünüz IP'den farklı olarak fiziksel sunucun bir tane daha IP'si olur.
O IP adres Cpanel'de gözükmez, hosting firmanızdan sorup öğrenmeniz gerekmekte.
Bu hatayı alırsanız hosting firmanın verdiği IP adrese'de banka gateway'i tarafından izin verilmesini sağlayın.

## Genel Kültür
### NonSecure, 3D Secure, 3DPay ve 3DHost ödeme modeller arasındaki farklar
- **3D** - Bankaya göre farklı isimler verilebilir, örn. 3D Full. Gateway'den (3D şifre girdiginiz sayfadan) döndükten sonra ödemeyi tamamlamak için banka gateway'ne 1 istek daha (_provizyon_ isteği) gönderir.
Bu isteği göndermeden ödeme tamamlanmaz.
- **3DPay** - Gateway'den (3D şifre girdiginiz sayfadan) döndükten sonra ödeme bitmiş sayılır. 3D ödeme yapıldığı gibi ekstra provizyon istek gönderilmez.
- **3DPay** - Bankaya göre farklı isimler verilebilir, örn. 3D Half. Gateway'den (3D şifre girdiginiz sayfadan) döndükten sonra ödeme bitmiş sayılır. 3D ödeme yapıldığı gibi ekstra provizyon istek gönderilmez.
- **3DHost** - Kredi kart girişi için kullanıcı bankanın sayfasına yönledirilir, kredi kart bilgileri girdikten sonra bankanın 3D gateway sayfasına yönlendirilir, ordan da websitenize geri yönlendirilir. Yönlendirme sonucunda ödeme tamanlanmış olur.
- **NonSecure** - Ödeme işlemi kullanıcı 3D onay işlemi yapmadan gerçekleşir.
- **NonSecure, 3D ve 3DPay** - Ödemede kredi kart bilgisi websiteniz tarafından alınır. **3DHost** ödemede ise banka websayfasından alınır.
## Otorizasyon, Ön Otorizasyon, Post Otorizasyon İşlemler arasındaki farklar

### Otorizasyon, Ön Otorizasyon, Ön Provizyon Kapama İşlemler arasındaki farklar
- **Otorizasyon** - bildiğimiz ve genel olarak kullandığımız işlem. Tek seferde ödeme işlemi biter.
Bu işlem için kullanıcıdan hep kredi kart bilgisini _alınır_.
İşlemin kütüphanedeli karşılığı `AbstractGateway::TX_PAY`
- **Ön Otorizasyon** - müşteriden parayı direk çekmek yerine, işlem sonucunda para bloke edilir.
Bu işlem için kullanıcıdan hep kredi kart bilgisini _alınır_.
İşlemin kütüphanedeli karşılığı `AbstractGateway::TX_PRE_PAY`
- **Post Otorizasyon** - ön provizyon sonucunda bloke edilen miktarın satışını tamamlar.
- **Ön Provizyon Kapama** - ön provizyon sonucunda bloke edilen miktarın satışını tamamlar.
Ön otorizasyon yapıldıktan sonra, örneğin 1 hafta sonra, Post Otorizasyon isteği gönderilebilinir.
Bu işlem için kullanıcıdan kredi kart bilgisi _alınmaz_.
Onun yerine bazı gateway'ler `orderId` degeri isteri, bazıları ise ön provizyon sonucu ödenen banka tarafındaki `orderId`'yi ister.
Satıcı _ön otorizasyon_ isteği iptal etmek isterse de `cancel` (Post Otorizasyon) isteği gönderir.
Post Otorizasyon İşlemin kütüphanedeli karşılığı `AbstractGateway::TX_POST_PAY`
- Bu 3 çeşit işlemler bütün ödeme modelleri (NonSecure, 3D, 3DPay ve 3DHost) tarafından desteklenir.


##Refund ve Cancel işlemler arasındaki farklar
### Refund ve Cancel işlemler arasındaki farklar
- **Refund** - Tamamlanan ödemeyi iade etmek için kullanılır.
Bu işlemi yapabilmek için ödeme yapıldıktan belli bir süre _sonra_ (örn. 12 saat) yapılabilir.
İade işlemi için _miktar zorunlu_, çünkü ödenen ve iade edilen miktarı aynı olmayabilir.
Expand Down
55 changes: 55 additions & 0 deletions docs/CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,60 @@
# Changelog

## [0.7.0] - 2022-05-18
### Changed
- `\Mews\Pos\PosInterface::prepare()` method artık sipariş verilerini (_currency, id, amount, installment, transaction type_) değiştirmez/formatlamaz.
Sipariş verilerinin formatlanmasını artık Data Request Mapper'de (örn. `PosNetRequestDataMapper`) istek göndermeden önce yapılır.

Önce:
```php
protected function preparePaymentOrder(array $order)
{
$installment = 0;
if (isset($order['installment']) && $order['installment'] > 1) {
$installment = $order['installment'];
}

return (object) array_merge($order, [
'id' => self::formatOrderId($order['id']),
'installment' => self::formatInstallment($installment),
'amount' => self::amountFormat($order['amount']),
'currency' => $this->mapCurrency($order['currency']),
]);
}
```
Şimdi:
```php
protected function preparePaymentOrder(array $order)
{
return (object) array_merge($order, [
'id' => $order['id'],
'installment' => $order['installment'] ?? 0,
'amount' => $order['amount'],
'currency' => $order['currency'] ?? 'TRY',
]);
}
```
- **GarantiPos** - tekrarlanan (`recurring`) ödeme desteği teklendi.
- **EstPos** - IP adres artık zorunlu değil.
- Language degerleri artık Gateway bazlı tanımlanmıyor. Önceden gateway bazlı:
```php
\Mews\Pos\Gateways\EstPos::LANG_TR;
\Mews\Pos\Gateways\EstPos::LANG_EN;
\Mews\Pos\Gateways\GarantiPos::LANG_TR;
\Mews\Pos\Gateways\GarantiPos::LANG_EN;
...
```
Şimdi sadece:
```php
\Mews\Pos\Gateways\AbstractGateway::LANG_TR;
\Mews\Pos\Gateways\AbstractGateway::LANG_EN;
```
- Siparişde `currency` ve `installment` artık zorunlu değil. Varsayılan olarak `currency=TRY`, `installment=0` olarak kabul edilir.
- Single Responsibility prensibe uygun olarak bütün gateway sınıflarında istek verilerini hazırlama Request Data Mapper'lere
(`EstPosRequestDataMapper`, `GarantiPosRequestDataMapper`, `InterPosRequestDataMapper`, `KuveytPosRequestDataMapper`, `PayForPosRequestDataMapper`, `PosNetRequestDataMapper`, `VakifBankPosRequestDataMapper`) taşındı.
Bununla birlikte bazı sabit değerler Gateway sınıflardan Request Data Mapper sınıflara taşındı.


## [0.6.0] - 2022-04-18
### Changed
- Kredi kart class'ları bütün gateway'ler için **tek** `Mews\Pos\Entity\Card\CreditCard` class'ı olacak şekilde güncellendi.
Expand Down

0 comments on commit 8823b02

Please sign in to comment.