QNB sanal POS'u (PayFor) için Omnipay sürücüsü
Türkçe | English
Mağazanızda QNB sanal POS'unuzla kartla ödeme almanızı sağlar. Müşteri QNB'nin ortak ödeme sayfasına gider, kartını orada girer, 3D Secure doğrulamasını yapar ve sitenize geri döner. Kart bilgisi sizin sunucunuzdan hiç geçmez.
Siteniz ──(imzalı form)──▶ QNB ortak ödeme sayfası ──(3D Secure)──▶ Siteniz (dönüş adresi)
Bu paket QNB'nin PayFor altyapısı içindir (yönetim ekranı vpos.qnb.com.tr). Eski NestPay / EST altyapısındaki QNB Finansbank üye iş yerleri için omnipay-nestpay kullanılır.
Özellikler
| Ödeme | Ortak ödeme sayfası (3D Host) |
| Taksit | 2-12 (bankanızla anlaştığınız kadar) |
| İade / iptal | refund() (tam ya da kısmi), void() (gün sonundan önce) |
| Sorgu | fetchTransaction() |
| Güvenlik | SHA-1 imza; dönüşte imza, üye iş yeri, sipariş no ve tutar denetimi |
composer require yasinkuyu/omnipay-qnb php-http/guzzle7-adapterPHP 8.1 ya da üstü gerekir.
| Ayar | Nedir? | Nereden bulunur? |
|---|---|---|
merchantId |
Üye iş yeri numarası | Bankanın gönderdiği bilgiler / sanal POS yönetim ekranı |
userCode |
API kullanıcı adı | Sanal POS yönetim ekranında açılan API kullanıcısı |
userPass |
API kullanıcı şifresi (iade / iptal / sorgu) | Aynı kullanıcı |
merchantPass |
3D anahtarı (imza için) | Sanal POS yönetim ekranı → 3D ayarları |
mbrId |
Kurum kodu | QNB için 5 (varsayılan) |
use Omnipay\Omnipay;
$gateway = Omnipay::create('Qnb');
$gateway->initialize([
'merchantId' => '085300000009704',
'userCode' => 'QNB_API_KULLANICI_3DPAY',
'userPass' => 'UcBN0',
'merchantPass' => '12345678',
'testMode' => true, // canlıya geçerken false
]);$response = $gateway->purchase([
'amount' => '149.90',
'currency' => 'TRY',
'transactionId' => 'SIP-10045', // sizin sipariş numaranız, her denemede benzersiz
'returnUrl' => 'https://magaza.com/odeme-donus.php', // başarılı ve başarısız dönüş buraya
'installment' => 3, // tek çekim için 1 ya da hiç yazmayın
])->send();
$response->redirect(); // tarayıcıyı QNB'nin ödeme sayfasına götüren formu basar ve gönderir$result = $gateway->completePurchase([
'transactionId' => 'SIP-10045', // KENDİ kaydınızdaki sipariş no
'amount' => '149.90', // KENDİ kaydınızdaki tutar
])->send();
if (!$result->isVerified()) {
// İmza tutmadı ya da sipariş no / tutar farklı: bu dönüşe güvenmeyin.
} elseif ($result->isSuccessful()) {
// Ödeme alındı.
$result->getTransactionReference(); // bankanın referans no (HostRefNum)
$result->getAuthCode();
$result->getMaskedCard();
} else {
echo $result->getMessage(); // ret nedeni ya da 3D Secure hatası
}Doğrulama nasıl çalışır? Banka dönüşü imzalar: üye iş yeri no, 3D anahtarı, sipariş no, onay kodu, sonuç kodu, 3D durumu, rastgele sayı ve kullanıcı adı birleştirilip SHA-1 alınır. Ödeme ancak sonuç kodu
00ve 3D durumu1ise başarılı sayılır.
$gateway->void(['transactionId' => 'SIP-10045'])->send(); // gün sonundan önce: iptal
$gateway->refund(['transactionId' => 'SIP-10045', 'amount' => '50.00'])->send(); // tam ya da kısmi iade
$status = $gateway->fetchTransaction(['transactionId' => 'SIP-10045'])->send();
$status->getData()['TxnResult']; // Success / Failed …isReadable() false dönerse bankanın yanıtı okunamamıştır: işlem gerçekleşmiş olabilir. Otomatik olarak yeniden
denemeyin; sanal POS ekranından kontrol edin.
testMode => true iken istekler QNB'nin test ortamına gider, para çekilmez. Yukarıdaki örnekteki bilgiler QNB'nin
herkese açık test hesabıdır. Test kartı: 4155 6501 0041 6111, son kullanma 01/28, CVV 123.
Test ortamının ödeme sayfası, dönüşleri ve sorgu / iptal / iade API'si buradan çalışır.
| Belirti | Neden |
|---|---|
| Banka hata sayfasına (GatewayError) yönleniyor | merchantPass, merchantId ya da userCode yanlış |
isVerified() hep false |
Farklı merchantPass ya da userCode, ya da dönüş alanları değiştirilmiş |
| İptal / iadede "V013 Seçili İşlem Bulunamadı" | Sipariş no yanlış ya da işlem gün sonuna girmiş (iptal yerine iade) |
| Dönüşte oturum düşüyor | Banka dönüşü siteler arası POST'tur: dönüş adresinde oturum çerezine güvenmeyin |
composer install
vendor/bin/phpunit- Omnipay: NestPay (EST / Payten) — İş Bankası, Akbank, Halkbank, Ziraat, TEB, QNB, ING, Şekerbank, Anadolubank sanal POS'u; 3D Pay Hosting
- Omnipay: GVP (Garanti BBVA) — Garanti BBVA sanal POS'u; Ortak Ödeme Sayfası
- Omnipay: Akbank — Akbank sanal POS'u (yeni altyapı); ortak ödeme sayfası
- Omnipay: Paratika — Paratika, VakıfPayS ve ZiraatPay ortak ödeme sayfası
- Omnipay: Paycell SDK — Turkcell Paycell ödeme sayfası (Web SDK)
- Omnipay: Paycell API — Turkcell Paycell ödeme API'si
- Omnipay: iyzico — iyzico ödeme formu
- Omnipay: PayTR — PayTR sanal POS
- Omnipay: Posnet — Yapı Kredi Posnet sanal POS'u
MIT — Yasin Kuyu