README

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

Desteklenen Payment Gateway'ler / Bankalar:

Gateway	Desktekleyen bankalar	Desteklenen Ödeme Tipleri	Desteklenen Sorgular
Tosla ^{(eski AKÖde)}	?	NonSecure 3DPay 3DHost	İptal İade Durum sorgulama Sipariş Tarihçesini sorgulama Özel Sorgu Taksit Oranları Taksit Fiyatları
IyzicoPos	Iyzico	NonSecure 3DSecure 3DHost	İptal İade (v2 API) Durum sorgulama Sipariş Tarihçesini sorgulama Geçmiş İşlemleri sorgulama Özel Sorgu Taksit Fiyatları BIN Sorgulama
PayTrPos	PayTr	NonSecure 3DPay^{(Direkt API)} 3DHost^{(iFrame API)}	İade Durum sorgulama Geçmiş İşlemleri sorgulama Özel Sorgu Taksit Oranları BIN Sorgulama
ParamPos	?	NonSecure 3DSecure 3DPay ^{(test edilmesi gerekiyor)}	İptal İade Durum sorgulama Geçmiş İşlemleri sorgulama Özel Sorgu Taksit Oranları BIN Sorgulama
Param3DHostPos	?	3DHost ^{(test edilmesi gerekiyor)}
AkbankPos ^{(Akbank'ın yeni altyapısı)}	Akbank	NonSecure 3DSecure 3DPay 3DHost Tekrarlanan Ödeme	İptal İade Sipariş Tarihçesini sorgulama Geçmiş İşlemleri sorgulama Özel Sorgu
AssecoPos ^{(Asseco/Payten)} eski EstV3Pos	Akbank TEB İşbank Şekerbank Halkbank Finansbank Ziraat	NonSecure 3DSecure 3DPay 3DHost 3DPayHost Tekrarlanan Ödeme	İptal İade Durum sorgulama Sipariş Tarihçesini sorgulama Özel Sorgu
PayFlex MPI VPOS V4	Ziraat Vakıfbank VPOS 7/24 İşbank	NonSecure 3DSecure Tekrarlanan Ödeme	İptal İade Durum sorgulama Özel Sorgu
PayFlex Common Payment V4 ^{(Ortak Ödeme)}	Ziraat Vakıfbank İşbank	3DPay 3DHost	Özel Sorgu
Garanti Virtual POS	Garanti	NonSecure 3DSecure 3DPay 3DHost Tekrarlanan Ödeme	İptal İade Durum sorgulama Sipariş Tarihçesini sorgulama Geçmiş İşlemleri sorgulama Özel Sorgu BIN Sorgulama
PosNet	YapıKredi	NonSecure 3DSecure	İptal İade Durum sorgulama Özel Sorgu
PosNetV1 ^{(JSON API)}	Albaraka Türk	NonSecure 3DSecure	İptal İade Durum sorgulama Özel Sorgu
PayFor	Finansbank Enpara Ziraat Katılım	NonSecure 3DSecure 3DPay 3DHost	İptal İade Durum sorgulama Sipariş Tarihçesini sorgulama Geçmiş İşlemleri sorgulama Özel Sorgu
InterPOS	Deniz bank	NonSecure 3DSecure 3DPay 3DHost	İptal İade Durum sorgulama Özel Sorgu
Kuveyt POS _TDV2.0.0	Kuveyt Türk	NonSecure 3DSecure
Kuveyt POS _TDV2.0.0 _{SOAP API}	Kuveyt Türk		İptal İade Durum sorgulama Özel Sorgu
VakifKatilimPos	Vakıf Katılım	NonSecure ^{(test edilmesi gerekiyor)} 3DSecure 3DHost ^{(test edilmesi gerekiyor)}	İptal İade Durum sorgulama Sipariş Tarihçesini sorgulama Geçmiş İşlemleri sorgulama Özel Sorgu

Ana başlıklar

Özellikler

Non Secure E-Commerce modeliyle ödeme (PosInterface::MODEL_NON_SECURE)
3D Secure modeliyle ödeme (PosInterface::MODEL_3D_SECURE)
3D Pay modeliyle ödeme (PosInterface::MODEL_3D_PAY)
3D Host modeliyle ödeme (PosInterface::MODEL_3D_HOST)
Sipariş/Ödeme durum sorgulama (PosInterface::TX_TYPE_STATUS)
Sipariş Tarihçesini sorgulama (PosInterface::TX_TYPE_ORDER_HISTORY)
Sipariş/Para iadesi yapma (PosInterface::TX_TYPE_REFUND ve PosInterface::TX_TYPE_PARTIAL_REFUND)
Sipariş iptal etme (PosInterface::TX_TYPE_CANCEL)
Geçmiş işlemleri sorgulama (PosQueryInterface::TX_TYPE_HISTORY)
Özel Sorgular (PosQueryInterface::TX_TYPE_CUSTOM_QUERY)
Taksit oranları sorgulama (PosQueryInterface::TX_TYPE_INSTALLMENT_RATES)
Taksit fiyatları hesaplama (PosQueryInterface::TX_TYPE_INSTALLMENT_PRICES)
BIN sorgulama (PosQueryInterface::QUERY_TYPE_BIN_LIST)
API istek verilerinin Listener'lerle gateway API'na gönderilmeden önce değiştirebilme
Farklı Para birimler ile ödeme desteği
Tekrarlanan (Recurring) ödeme talimatları
PSR-3 logger desteği
PSR-18 HTTP Client desteği

Farklı Gateway'ler Tek İşlem Akışı

Bir (3DSecure, 3DPay, 3DHost, NonSecure) ödeme modelden diğerine geçiş çok az değişiklik gerektirir.
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'lere gönderilecek değerler de genel olarak aynı formatta olacak şekilde normalize edilmiştir.

Minimum Gereksinimler

PHP >= 8.0
ext-dom
ext-json
ext-openssl
ext-libxml
ext-zlib
ext-SimpleXML
PSR-18: HTTP Client
PSR-14: Event Dispatcher

Kurulum

Frameworks

Symfony kurulum için mews/pos-bundle kullanabilirsiniz.
Laravel kurulum için mews/laravel-pos kullanabilirsiniz.

Basic kurulum

$ composer require symfony/event-dispatcher mews/pos

Kütüphane belli bir HTTP Client'ile zorunlu bağımlılığı yoktur. PSR-18 HTTP Client standardına uyan herhangi bir kütüphane kullanılabilir. Projenizde zaten kurulu PSR-18 uygulaması varsa otomatik onu kullanır.

Veya hızlı başlangıç için:

$ composer require php-http/curl-client nyholm/psr7 symfony/event-dispatcher mews/pos

Diğer PSR-18 uygulamasını sağlayan kütüphaneler: https://packagist.org/providers/psr/http-client-implementation

Sonra kendi projenizin dizinindeyken alttaki komutu çalıştırarak ayarlar dosyasını projenize kopyalayınız.

$ cp ./vendor/mews/pos/config/pos_production.php ./pos_prod_ayarlar.php

Test ortamda geliştirecekseniz test ayarları da kopyalayınız:

$ cp ./vendor/mews/pos/config/pos_test.php ./pos_test_ayarlar.php

Kopyaladıktan sonra ayarlardaki kullanmayacağınız banka ayarları silebilirsiniz.

gateway_configs.test_mode hakkında: Bu ayar yalnızca PayTrPos ve GarantiPos için istek verisini etkiler (banka API'sine test/prod göstergesi gönderir). Diğer tüm gateway'lerde test ve production ortamı ayrımı, yukarıdaki endpoint URL'leri ile yapılır; bu gateway'ler için test_mode: true ayarlamak bir etkisi olmaz ve logger'da uyarı mesajı oluşturur.

Bundan sonra Pos nesnemizi, yeni ayarlarımıza göre oluşturup kullanmamız gerekir. Örnek:

// 1. Banka hesabı oluşturunuz (her banka için farklı bir factory metodu vardır)
$account = \Mews\Pos\Factory\AccountFactory::createAkbankPosAccount(
    'akbank-pos',
    'MERCHANT_SAFE_ID',
    'TERMINAL_SAFE_ID',
    'SECRET_KEY'
);

// 2. Event dispatcher oluşturunuz (symfony/event-dispatcher önerilir)
// Elinizde farklı PSR-14 uygumlu EventDispatcher var ise kullanabilirsiniz.
$eventDispatcher = new \Symfony\Component\EventDispatcher\EventDispatcher();

// 3. Ayarları yükleyip ilgili bankanın dilimini alınız
$yeniAyarlar = require __DIR__ . '/pos_prod_ayarlar.php';
// veya test ortamı için $yeniAyarlar = require __DIR__ . '/pos_test_ayarlar.php';
$bankAyarlari = $yeniAyarlar['banks'][$account->getBankName()];

// 4. Gateway nesnesini oluşturunuz
$pos = \Mews\Pos\Factory\PosFactory::create($account, $bankAyarlari, $eventDispatcher);

Kütüphanede yer alan pos_production.php ve pos_test.php ayar dosyaları projenizde direk kullanmayınız! Yukarda belirtildiği gibi kopyalayarak kullanmanız tavsiye edilir.

Farklı Banka Sanal Poslarını Eklemek

Projenize kopyaladığınız ./pos_prod_ayarlar.php dosyasına farklı banka ayarı eklemek için alttaki örneği kullanabilirsiniz.

<?php

return [
    // Banka sanal pos tanımlamaları
    'banks'         => [
        'akbank'    => [
            // AKBANK T.A.S.
            'class' => \Mews\Pos\Gateway\AssecoPos::class,
            'lang'  => \Mews\Pos\PosInterface::LANG_TR, // optional
            'gateway_endpoints'  => [
                'payment_api'     => 'https://www.sanalakpos.com/fim/api',
                'gateway_3d'      => 'https://www.sanalakpos.com/fim/est3Dgate',
                'gateway_3d_host' => 'https://sanalpos.sanalakpos.com.tr/fim/est3Dgate',
            ],
        ],

        // Yeni eklenen banka
        'isbank'    => [ // unique bir isim vermeniz gerekir.
            // İŞ BANKASI .A.S.
            'class' => \Mews\Pos\Gateway\AssecoPos::class, // Altyapı sınıfı
            'lang'  => \Mews\Pos\PosInterface::LANG_TR, // optional
            'gateway_endpoints'  => [
                'payment_api'     => 'https://sanalpos.isbank.com.tr/fim/api',
                'gateway_3d'      => 'https://sanalpos.isbank.com.tr/fim/est3Dgate',
            ],
        ],
    ]
];

Örnek Kodlar

Örnekleri /docs ve /examples dizini içerisinde bulabilirsiniz.

/examples kodları çalıştırmak için alttaki bölüme bakınız.

Popup Window'da veya iframe içinde ödeme yapma

Müşteriyi banka sayfasına redirect etmeden iframe üzerinden veya popup window üzerinden ödeme akışı examples'da ve /docs'da 3D ödeme ile örnek PHP ve JS kodlar yer almaktadır.

Troubleshoots

Session sıfırlanması

Cookie session kullandığınızda, kullanıcı gatewayden geri websitenize yönlendirildiğinde session sıfırlanabilir. Response'da samesite değeri set etmeniz gerekiyor. çözüm.

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 adresi cPanel'de gözükmez, hosting firmanızdan sorup öğrenmeniz gerekmekte. Bu hatayı alırsanız hosting firmanın verdiği IP adresine de banka gateway'i tarafından izin verilmesini sağlayın.

Debugging

Kütüphane PSR-3 standarta uygun logger uygulamayı destekler. Örnekler: https://packagist.org/providers/psr/log-implementation .

Monolog logger kullanım örneği:

composer require monolog/monolog

$handler = new \Monolog\Handler\StreamHandler(__DIR__.'/../var/log/pos.log', \Psr\Log\LogLevel::DEBUG);
$logger = new \Monolog\Logger('pos', [$handler]);
$pos = \Mews\Pos\Factory\PosFactory::create(
    $account,
    $config['banks'][$account->getBankName()],
    $eventDispatcher,
    null,
    null,
    $logger
);

Genel Kültür

Ödeme modelleri hakkında bilgi edinmek istiyorsanız bu makaleyi inceleyebilirsiniz.

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üphanedeki karşılığı PosInterface::TX_TYPE_PAY_AUTH
Ö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üphanedeki karşılığı PosInterface::TX_TYPE_PAY_PRE_AUTH
Ön Provizyon Kapama - ön provizyon sonucunda bloke edilen miktarın çekimini gerçekleştirir. Ön otorizasyon yapıldıktan sonra, örneğin 1 hafta sonra, Post Otorizasyon isteği gönderilebilir. Bu işlem için kullanıcıdan kredi kart bilgisi alınmaz. Onun yerine bazı gateway'ler orderId değeri istenir, bazıları ise ön provizyon sonucu dönen banka tarafındaki orderId'yi ister. Satıcı ön otorizasyon isteği iptal etmek isterse de cancel isteği gönderir. Post Otorizasyon İşlemin kütüphanedeki karşılığı PosInterface::TX_TYPE_PAY_POST_AUTH. Bu işlem sadece NonSecure ödeme modeliyle gerçekleşir.
TX_TYPE_PAY_AUTH vs TX_TYPE_PAY_PRE_AUTH işlemler genelde bütün ödeme modelleri (NonSecure, 3DSecure, 3DPay ve 3DHost) tarafından desteklenir.

Refund ve Cancel işlemler arasındaki farklar

Refund - Tamamlanan ödemeyi iade etmek için kullanılır. Bu işlem bazı gatewaylerde sadece gün kapandıktan sonra yapılabilir. İade işlemi için miktar zorunlu, çünkü ödenen ve iade edilen miktarı aynı olmayabilir. İşlemin kütüphanedeki karşılığı PosInterface::TX_TYPE_REFUND
Cancel - Tamamlanan ödemeyi iptal etmek için kullanılır. Ödeme yapıldıktan sonra gün kapanmadan yapılabilir. Gün kapandıktan sonra refund işlemi kullanmak zorundasınız. Genel olarak miktar bilgisi istenmez, ancak bazı Gateway'ler ister. İşlemin kütüphanedeki karşılığı PosInterface::TX_TYPE_CANCEL

Docker ile Örnek Kodların Denenmesi

Makinenizde Docker kurulu olması gerekir.
Örnekleri çalıştırmadan önce banka hesap bilgilerini ortam değişkenleri aracılığıyla sağlamanız gerekmektedir: examples/.env.dist dosyasını examples/.env olarak kopyalayın:
```
cp examples/.env.dist examples/.env
```
examples/.env dosyasını açıp kullanmak istediğiniz banka(lar)a ait hesap bilgilerini (merchant ID, şifre, API anahtarı vb.) doldurun.
Projenin root klasöründe docker-compose up -d komutu çalıştırınız.
docker container'de composer install çalıştırınız.
```
docker compose exec -it web composer install
```

Note: localhost port 80 boş olması gerekiyor. Sorunsuz çalışması durumda kod örneklerine http://localhost/asseco/3d/index.php şekilde erişebilirsiniz. http://localhost/ URL projenin examples klasörünün içine bakar.

Unit testler çalıştırma

Projenin root klasöründe bu satırı çalıştırmanız gerekiyor

$ docker compose exec -it web composer test

Değerli yorum, öneri ve katkılarınız için teşekkür ederiz.

Sorun bulursanız veya eklenmesi gereken POS sistemi varsa lütfen issue oluşturun.

License

MIT

mews / pos

Maintainers

Package info

Statistics

Security