README

Türk bankaları ve ödeme kuruluşları için tek API'li PHP sanal POS / ödeme geçidi entegrasyon kütüphanesi.

Onlarca bankanın birbirinden farklı protokollerini (XML, SOAP, HTML form-post, JSON/REST) tek bir PHP arayüzünün arkasına gizler. Banka değiştirmek için yalnızca bank slug'ını değiştirirsiniz — uygulama kodunuz aynı kalır.

mews/pos projesinden fork'lanmış, Ankapix\SanalPos namespace'ine taşınmış ve Türkiye pazarındaki yeni banka/aggregatörlerle genişletilmiştir.

İçindekiler

• Özellikler
• Desteklenen Bankalar
• Gereksinimler
• Kurulum
• Hızlı Başlangıç
• 3D Secure Akışı
• Banka Bazında account Alanları
• Taksit Sorgulama & Kart Tipi
• İade / İptal / Durum Sorgu
• Ödeme Modelleri
• Yanıt Şeması
• Yeni Banka / Ortam Ekleme
• Örnekler
• Katkı
• Lisans

Özellikler

• Tek API, çok banka — regular, 3d, 3d_pay, 3d_pay_hosting ödeme modelleri.
• Auth / PreAuth / PostAuth işlem tipleri (pay / pre / post).
• İade, iptal, durum sorgu, işlem geçmişi — banka destekliyorsa.
• Normalize edilmiş yanıt — her banka farklı dönse de yanıt aynı alan adlarıyla okunur.
• Tek dosyalık sürücü kayıt defteri (config/sanalpos.php); yeni banka eklemek kod değil konfigürasyon işidir.

Desteklenen Bankalar

Tam liste ve uç nokta (endpoint) URL'leri için: config/sanalpos.php.

Gereksinimler

• PHP 7.4 – 8.5 (çekirdek 7.2+ derlenir, ancak module/ altındaki bazı gömülü SDK'lar 7.4 ister; PHP 8.0–8.5'te test edilmiştir)
• Eklentiler: ext-curl, ext-dom, ext-json, ext-openssl, ext-SimpleXML

Kurulum

Paket Packagist'te değildir; GitLab deposundan VCS repository ile çekilir. Projenizin composer.json dosyasına:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@gitlab.com:Ankapix/sanalpos-entegrasyonlari.git"
        }
    ],
    "require": {
        "ankapix/sanalpos-entegrasyonlari": "^1.0"
    }
}

Ardından:

composer update ankapix/sanalpos-entegrasyonlari

Versiyon pinleme: dev-master yerine ^1.0 kullanın. Böylece master'a atılan her commit üretiminizi etkilemez; yalnızca yeni bir v1.x etiketi yayınlandığında, kontrollü biçimde güncellersiniz.

Hızlı Başlangıç

regular (3D'siz, doğrudan) ödeme:

require 'vendor/autoload.php';

use Ankapix\SanalPos\Pos;

$account = [
    'bank'      => 'akbank',     // sürücüyü seçen slug
    'model'     => 'regular',
    'client_id' => 'XXXXXXX',
    'username'  => 'XXXXXXX',
    'password'  => 'XXXXXXX',
    'env'       => 'test',       // 'test' | 'production'
];

$pos = new Pos($account);

$order = [
    'id'          => 'ORDER-' . time(),
    'amount'      => 320.00,
    'installment' => 0,
    'currency'    => 'TRY',      // TRY, USD, EUR, GBP ...
    'ip'          => $_SERVER['REMOTE_ADDR'],
    'transaction' => 'pay',      // pay=Auth, pre=PreAuth, post=PostAuth
];

$card = [
    'number' => '4355084355084358',
    'month'  => '12',
    'year'   => '26',
    'cvv'    => '000',
];

try {
    $pos = new Pos($account);

    // prepare() ZORUNLU — order ve card'ı sürücüye yükler, payment() onları okur.
    $pos->prepare($order, $card);

    $payment  = $pos->payment($card);
    $response = $payment->response;     // = $pos->bank->response

    if ($pos->isSuccess()) {
        echo "Onaylandı. Auth code: {$response->auth_code}";
    } else {
        echo "Başarısız ({$response->error_code}): {$response->error_message}";
    }
} catch (\Ankapix\SanalPos\Exceptions\BankNotFoundException $e) {
    // config/sanalpos.php'de tanımsız 'bank' slug'ı
} catch (\Ankapix\SanalPos\Exceptions\BankClassNullException $e) {
    // slug var ama 'class' boş
} catch (\Exception $e) {
    // ağ / banka / doğrulama hatası
}

3D Secure Akışı

3D ödemeler iki adımlıdır ve iki ayrı HTTP isteğinde gerçekleşir. success_url / fail_url (bazı bankalarda return_url) banka geri dönüşünün vuracağı kendi callback URL'nizdir — sipariş kimliğini (order.id) o URL'den geri okuyup ödemeyi orada doğrularsınız.

Adım 1 — 3D formu üret ve istemciye gönder. get3dForm(), otomatik submit olan hazır HTML döndürür (form alanlarını siz kurmazsınız):

$account = [
    'bank'        => 'akbank_est',
    'model'       => '3d',          // veya '3d_pay'
    'client_id'   => $musteriNo,
    'username'    => $kullaniciAdi,
    'password'    => $sifre,
    'store_key'   => $storeKey,     // 3D modelinde zorunlu
    'env'         => 'production',
];

$order = [
    'id'          => $odemeNo,      // kendi benzersiz ödeme kodunuz
    'amount'      => 320.00,
    'installment' => $taksit,       // 1 = tek çekim
    'currency'    => 'TRY',
    'ip'          => $request->getClientAddress(),
    'success_url' => 'https://api.site.com/sanalpos/basarili/' . $odemeId,
    'fail_url'    => 'https://api.site.com/sanalpos/basarisiz/' . $odemeId,
    'transaction' => 'pay',
    'lang'        => 'tr',
    'rand'        => microtime(),
];

$pos = new Pos($account);
$pos->prepare($order, $card);

$html = $pos->get3dForm();          // <form ... auto-submit> HTML'i
// Bu HTML'i tarayıcıya basın (ör. iframe / sayfa) — kullanıcı bankanın 3D sayfasına gider.

Adım 2 — Banka success_url'inize POST'lar; ödemeyi orada doğrulayıp tahsil edin. Aynı account ile (karta gerek yok) siparişi yeniden kurup payment() çağırırsınız:

// success_url callback'i — order.id'yi kendi kaydınızdan geri yüklediniz
$pos = new Pos($account);          // adım 1'deki ile aynı account
$pos->prepare($order);             // kart YOK; banka POST'u $_POST'tan okunur

$payment  = $pos->payment();       // banka dönüşünü doğrular + tahsil eder
$response = $payment->response;

if ($pos->isSuccess()) {
    // ödemeyi onaylandı olarak işaretle
} else {
    // $response->error_code / $response->error_message
}

model 3d mi 3d_pay mı olacağı bankaya göre değişir; uygulamanızda bir bayrakla seçebilirsiniz (B4B'de is3dPay ayarına göre '3d_pay' : '3d').

Banka Bazında account Alanları

Her sürücü farklı kimlik alanları bekler. Aşağıdaki tablo, üç ortak alanın (bank, model, env) üzerine eklenmesi gerekenleri ve siparişe eklenen sürücüye özgü order alanlarını listeler (gerçek kullanım: B4B SanalposController).

Bazı sağlayıcılar (Paynet, İyzico) tutarı kuruş bazında bekler — örnekte amount * 100. order_list her sağlayıcıda farklı şekildedir (İyzico: code/title/category/amount, Moka/İpara: Code/Title/Quantity/Price, ZiraatPay/VakıfPay: productCode/name/amount/quantity ...).

Taksit Sorgulama & Kart Tipi

Kart BIN'i (ilk 6 hane) ile taksit oranlarını sorgulamak için getInstallmentList():

$pos = new Pos($account);

// Kart tipi (örn. PayTR'de taksit tablosunu seçmek için)
$pos->setCard(['number' => $bin6]);
$kartTipi = $pos->getCardType();

// Taksit oranları — yanıt şekli sağlayıcıya göre değişir
$liste = $pos->getInstallmentList(['number' => $bin6, 'amount' => $tutar]);
foreach ($liste->response->data as $oran) {
    // $oran->instalment / installments_number / getInstallmentNumber() ...
}

getInstallmentList() yanıtı sağlayıcıya göre farklıdır (Paynet, İPara, İyzico, PayTR, QNB Pay, Net Tahsilat). Uygulamanızda sağlayıcıya göre dallanın (B4B'deki taksitAction bunun tam örneğidir).

İade / İptal / Durum Sorgu

Bu işlemler sürücü üzerinden çağrılır ($pos->bank->...):

// İade
$pos->bank->refund(['order_id' => '...', 'amount' => '100']);

// İptal
$pos->bank->cancel(['order_id' => '...']);

// Durum sorgu
$pos->bank->status(['order_id' => '...']);

// İşlem geçmişi (destekleyen bankalarda)
$pos->bank->history(['order_id' => '...']);

$response = $pos->bank->response;     // her durumda normalize yanıt buradadır

Desteklenen alanlar bankaya göre değişir; ayrıntı için ilgili sürücüyü ve examples/<banka>/regular/{refund,cancel,status,history}.php dosyalarını inceleyin.

Ödeme Modelleri

$account['model'] ile belirlenir:

$order['transaction']: pay (Auth), pre (PreAuth), post (PostAuth). Para birimi $order['currency'] ISO kodu olarak verilir (TRY, USD, ...); kütüphane ISO 4217 numeriğe (949, 840, ...) çevirir. TL, TRY ile eşdeğerdir.

Yanıt Şeması

Hangi banka olursa olsun yanıt $pos->bank->response üzerinde aynı alan adlarıyla okunur:

isSuccess() / isError() yardımcıları işlem sonucunu döner.

Yeni Banka / Ortam Ekleme

Yeni banka eklemek kod değil konfigürasyon işidir. config/sanalpos.php içine bir banks girdisi eklenir:

'yeni_banka' => [
    'name'  => 'Yeni Banka',
    'class' => Ankapix\SanalPos\EstPos::class,   // protokolü taşıyan sürücü
    'urls'  => [
        'production' => 'https://.../api',
        'test'       => 'https://.../api',
        'gateway'    => [                          // 3D form post hedefi
            'production' => 'https://.../3Dgate',
            'test'       => 'https://.../3Dgate',
        ],
    ],
],

Banka mevcut bir platformu (EST/NestPay, GVP, PosNet ...) kullanıyorsa hazır sürücüyü yeniden kullanın; tamamen yeni bir protokolse PosInterface'i uygulayan ve PosHelpersTrait'i kullanan yeni bir sürücü yazın.

Örnekler

Çalışan örnekler examples/<banka>/<model>/ altındadır (her biri _config.php, index.php, form.php/post.php, response.php 4'lüsü). Bir PHP sunucusunu ilgili dizine yönlendirip _config.php içindeki $path değerini yerel URL'nize göre ayarlayın.

⚠️ Bazı örnekler upstream fork'tan kalma Mews\Pos namespace'i içerir; kopyalarken Ankapix\SanalPos ile değiştirin.

Katkı

Pull request ve issue'lar GitLab deposu üzerinden kabul edilir. Yeni banka sürücüsü eklerken mevcut sürücülerin normalize yanıt alan adlarını birebir takip edin ki çağıran kod banka-bağımsız kalsın.

Lisans

MIT lisansı altında yayınlanmıştır.