diff --git a/README.md b/README.md index 9f0291ef..19d325f6 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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`) @@ -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. @@ -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 @@ -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. @@ -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); @@ -233,28 +244,32 @@ 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. @@ -262,8 +277,7 @@ Satıcı _ön otorizasyon_ isteği iptal etmek isterse de `cancel` (Post Otoriza 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. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index bd9af970..97bced8c 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -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.