Download the PHP package voxyfy/anadolupay without Composer

AnadoluPay

Türk bankalarının sanal POS'ları için tek arayüz.

Türkiye'de banka entegrasyonu yazmak, aynı işi on yedi kez farklı şekilde yapmaktır. Garanti tutarı kuruş cinsinden tam sayı ister, NestPay ondalıklı dizgi. Garanti hash'i ayraçsız birleştirip büyük harfe çevirir, NestPay alanları sıralayıp | ile birleştirir, PosNet ; kullanır. Kuveyt Türk size form alanları değil hazır bir HTML sayfası döner. VakıfBank provizyon adımında kart bilgisini bir daha ister. Bunların hiçbiri dokümantasyonda yan yana yazmaz; her birini ayrı ayrı öğrenirsiniz.

Bu paket o farkları tek bir sözleşmenin arkasına alır:

Bankayı değiştirmek için 'garanti' yerine 'akbank' yazmak yeterlidir.

Çalışan bir örnek uygulama için: Voxyfy/anadolupay-laravel

Laravel'e değil düz Node.js/TypeScript'e bağlı kalmak isteyenler için aynı protokol bilgisiyle taşınan bir port da var: Voxyfy/anadolupay-node (npm) — test etmek için Voxyfy/anadolupay-node-example.

Aynı "çok sağlayıcı, tek arayüz" mimarisini kargo firmaları için uygulayan bir kardeş proje de var: Voxyfy/anadoluship (npm) — MNG, UPS, Yurtiçi, Aras, PTT ve Sürat Kargo için Node.js/TypeScript SDK'sı.

LLM API'lerine (OpenAI/Anthropic/Gemini) müşteri verisi gönderirken KVKK riskini azaltmak için de bir kardeş kütüphane var: Voxyfy/anadolushield (npm) — TCKN, VKN, IBAN, telefon, isim gibi kişisel verileri LLM'e göndermeden önce maskeler.

KVKK/GDPR uyumlu çerez rızası için de bir kardeş kütüphane var: Voxyfy/anadolucookie — framework'e bağımlı olmayan çerez rıza (cookie consent) banner kütüphanesi.

Ne yapmaz: Arayüz üretmez, sipariş durumu tutmaz, stok düşmez, fatura kesmez. Ödeme akışını yürütür ve yanıtı normalleştirir; gerisi sizin uygulamanızın işi.

Canlıya çıkmadan önce okuyun

Bu paketteki protokoller bankaların public dokümantasyonuna göre yazıldı ve istek üretimi, imza ve yanıt eşlemesi birim testleriyle kilitlendi. Ancak banka driver'larının çoğu gerçek bir bankaya karşı çalıştırılmadı. (Ölçülmüş olanlar için Doğrulama durumu tablosuna bakın — hangisinin nereye kadar götürüldüğü orada yazılıdır.)

Testler benim yazdığım algoritmayı doğrular, bankanın beklediğini değil. Bir alanın sırası yanlışsa test yeşil kalır, banka işlemi reddeder. Kullanacağınız her banka için kendi test üye işyeri bilgilerinizle en az bir 3D Secure satış ve bir iade çalıştırın. Hash hesabında bankalar zaman zaman kuruluma özel farklılıklar tanımlıyor.

Bu uyarı banka driver'ları içindir. iyzico driver'ı bunun dışındadır: sandbox ortamında uçtan uca çalıştırılıp doğrulanmıştır — bkz. Doğrulama durumu.

Doğrulama durumu

Her driver aynı ölçüde doğrulanmış değil. Bu tablo hangisinin nereye kadar ölçüldüğünü gösterir; "test var" ile "gerçekten çalışıyor" aynı şey değildir.

iyzico'da tam olarak ne doğrulandı

2026-08-09'da iyzico sandbox'ında, örnek projeden, tarayıcıyla tamamlanan bir 3D Secure satış (100,00 TL, tek çekim, resmî test kartı) şunları kanıtladı:

• Authorization başlığı (IYZWSv2) — iyzico isteği kabul etti, paymentId verdi
• Initialize yanıt imzası — doğrulama açıkken geçti
• 3DS dönüş imzası — gerçek dönüş, conversationData:conversationId:mdStatus:paymentId:status sırasıyla birebir eşleşti
• Provizyon (auth) yanıt imzası — /payment/3dsecure/auth yanıtı doğrulandı, authCode alındı

Aynı oturumda şu işlemler de sandbox'a karşı çalıştırıldı:

Bunlar doğrulanmadı: diğer ödeme modelleri (3d_pay, 3d_host, regular) ve canlı ortam. Sandbox'ta çalışan bir akış canlıda da çalışır diye bir garanti yoktur; üye işyeri tanımınız farklı olabilir.

iyzico'nun ayrı bir iptal işlemi yoktur — bu yüzden driver SupportsCancellation arayüzünü uygulamaz. Aynı gün yapılan tam iadeyi iyzico kendisi iptal olarak işler; yukarıdaki testte yanıt transactionType: CANCEL döndü. Yani iptal etmek için refund() çağırmanız yeterli.

İçindekiler Kurulum · Doğrulama durumu · Örnek proje · Desteklenen bankalar · Nasıl çalışır · Yapılandırma · Ödeme akışı · İade ve iptal · Ödeme modelleri · Yetenekler · Tutarlar · Bankaların tuhaflıkları · Hata yönetimi · Event'ler · Loglama · Test ortamı · Test kartları · Güvenlik · Yeni banka eklemek · Yol haritası

Kurulum

PHP 8.2+, Laravel 12 veya 13. Auto-discovery açıktır, ek adım yoktur.

Laravel 13 en az PHP 8.3 ister; PHP 8.2 kullanıyorsanız Laravel 12'de kalırsınız. CI her iki kombinasyonu da koşar.

Uçtan uca kurulmuş bir Laravel projesi görmek isterseniz anadolupay-laravel deposu ödeme başlatma, 3D dönüşü ve iade akışlarını örnekliyor.

Desteklenen bankalar

Türkiye'deki sanal POS'lar birkaç ortak altyapı ailesine iner. Aynı aileyi kullanan bankalar aynı driver'ı paylaşır; aralarındaki fark yalnızca uç nokta ve kimlik bilgisidir.

Aynı banka birden fazla satırda görünebilir. Bir bankanın iki farklı sanal POS ürünü varsa her biri ayrı bir driver'dır: ayrı protokol, ayrı kod, ayrı doğrulama durumu. Birinin ölçülmüş olması diğeri hakkında hiçbir şey söylemez. Bankanın adının yanındaki parantez hangisi olduğunu belirtir — örneğin akbank (NestPay) ile akbank-pos (yeni JSON API) akraba bile değildir. Ayrıca akbank-pos aşağıdaki ödeme kuruluşları tablosunda yer alır. Hangisinin size tanımlandığını sanal POS sözleşmenizden teyit edin.

Tablodaki Test sütunu, o driver'ın sağlayıcının kendi ortamına karşı koşulup koşulmadığını söyler — geri kalan sütunlar yalnızca protokolün uygulandığını gösterir, çalıştığını değil:

Ödeme kuruluşları:

Aynı bankanın iki driver'ı varsa ikisi de gerçektir; hangisinin tanımlandığını sanal POS sözleşmenizden teyit edin:

• Akbank → akbank (eski NestPay) veya akbank-pos (yeni JSON API)
• Ziraat → ziraat (NestPay) veya ziraat-payflex (PayFlex)
• QNB Finansbank → qnb (NestPay) veya qnb-payfor (PayFor). qnb'nin varsayılan adresi www.fbwebpos.com gerçek ortam için artık DNS'te çözülmüyor — ama domain terk edilmiş değil, hâlâ Finansbank'a kayıtlı ve DNSSEC ile aktif imzalanıyor; sadece web kaydı kaldırılmış. Test ortamı ortak Asseco ucunda (entegrasyon.asseco-see.com.tr) çalışıyor: Asseco'nun resmi "Finansbank Test Dokümanı"nda yayınlanmış, bankalar arası paylaşılan bir kimlik var (ClientId 600100000, Storekey 123456, API kullanıcı/şifre FINANSAPI/FINANS06). 2026-08-11'de örnek projeden ölçüldü: 3D Secure tam turu geçti (mdStatus 1, imza ve CAVV doğrulandı, iki farklı kartla tekrarlandı) ama provizyon ikisinde de aynı jenerik hatayla düştü (ProcReturnCode 99, ERRORCODE ISO8583-19) — Türkiye Finans'takiyle aynı kalıp: paylaşılan kimlik 3D'yi geçirir, provizyona yetkili değil. Kendi üye işyerinizle deneyin; qnb-payfor şu an daha az riskli çünkü uçtan uca doğrulanmış.

Nasıl çalışır

Bankalar arasındaki fark yüzeyde protokol (XML / JSON / SOAP / form), derinde imza algoritmasıdır. Paket bu iki katmanı ayırır:

Bir driver yalnızca yedi metodu doldurur: build3dFormFields(), checkCallbackHash(), is3dAuthSuccess(), provision(), mapCallbackResponse(), mapProvisionResponse(), extractOrderId().

Akış kontrolü, hata yönetimi, HTTP ve loglama temel sınıfta tek yerde durur. Bir bankada düzeltilen akış hatası hepsinde düzelir; bu, on yedi kopyanın ayrı ayrı bakımını yapmaktan farkı.

Dönen PaymentResponse ve VerificationResponse bankadan bağımsızdır: hangi driver'ı kullanırsanız kullanın success, paymentId ve status aynı anlama gelir. Bankanın ham yanıtı raw içinde korunur — normalleştirme bilgi kaybı yaratmaz.

Yapılandırma

Yalnızca kullandığınız bankanın değişkenlerini doldurun. Diğer preset'ler boş kalabilir; yalnızca çağrıldıklarında hata verirler.

Aynı kavramın bankalarda farklı adları var:

Tüm anahtarlar için yayınladığınız config/anadolupay.php dosyasına bakın.

Sipariş numarası

Sipariş numarasını kendiniz veriyorsanız hiçbir şey değişmez. Vermek istemiyorsanız orderId'yi boş geçin; paket ön eki yapılandırmadan alıp numarayı üretir:

Numara A-Z0-9 ile sınırlıdır ve rastgeledir; sayaç tutulmaz. Sebebi: sipariş numarası bankada kalıcı bir anahtardır — aynı numara ikinci kez gönderilirse işlem reddedilir ve numara iade/sorgulamada da kullanıldığı için sonradan değiştirilemez. Sayaç bunun için kalıcı depolama ve kilit gerektirir.

İki sınırı bilerek seçin:

• PosNet (Yapı Kredi, Albaraka) ve Paycell numarayı 20 karaktere sığdırır. Ön ek bu bütçeden düşer; taştığında driver sessizce kesmek yerine hata verir.
• Paycell ön eki tamamen atar. Referans numarasını üretirken rakam dışındaki her karakteri siler, yani benzersizlik tamamen rastgele bölümdedir.

Ödeme akışı

Türk banka sanal POS'larında 3D Secure bir GET yönlendirmesi değil, bankanın 3D geçidine yapılan bir form POST'udur. Akış üç adımdır:

1 · Ödemeyi başlat

toHtmlForm() otomatik gönderilen bir sayfa üretir. Formu kendiniz render etmek isterseniz:

Kuveyt Türk, Vakıf Katılım ve Param form alanı yerine hazır bir HTML sayfası döner; bu durumda formFields boştur ve içerik $response->htmlContent içindedir. toHtmlForm() iki durumu da doğru ele alır — elle uğraşmak yerine onu kullanın.

2 · Dönüşü doğrula

verify() sırayla: dönüş hash'ini doğrular (eşleşmezse InvalidSignatureException), 3D doğrulama durumunu kontrol eder, klasik 3D Secure modelinde bankaya provizyon isteğini gönderir. 3D Pay ve 3D Host'ta provizyon banka tarafında tamamlandığı için ikinci istek atılmaz.

PayFlex (VakıfBank / Ziraat) sipariş bağlamı ister. Banka provizyon adımında kart bilgisini ve tutarı yeniden sorar ama bunları dönüşte göndermez — siz sağlarsınız:

İade ve iptal

Gün sonu kapanmadan önce iade değil iptal kullanın — daha hızlı ve komisyonsuzdur:

Bazı bankalar işlemi sipariş numarasıyla değil, kendi referanslarıyla eşler. Bu referansı ödeme sırasında saklayıp metadata ile geçin:

cancel() ve status() şu an PaymentGatewayInterface'de değil, driver'lara özel metotlardır. Yani statik tip güvenliği yoktur; desteklemeyen bir driver'da çağırırsanız runtime'da patlar. Hangi driver'ın hangisini desteklediği tabloda yazıyor.

Ödeme modelleri

3D Host modelinde card vermeniz gerekmez.

Yetenekler

Her banka her işlemi sunmaz. Bu bir eksiklik değil, sağlayıcı sınırıdır: PayTR iptal (void) API'si sunmaz, Akbank'ın yeni API'si tekil durum sorgusu sunmaz, Kuveyt Türk ön provizyon sunmaz.

Paket bunu tip düzeyinde bildirir — desteklenmeyen bir metodu çağırmadan önce instanceof ile kontrol edin:

Arayüzler: SupportsStatusQuery, SupportsCancellation, SupportsPreAuthorization, SupportsOrderHistory, SupportsBinQuery, SupportsInstallmentQuery, SupportsRecurringPayments.

Durum sorgusu

Zaman aşımı gibi belirsiz durumları kapatmanın tek yolu budur.

Bankaların birbirine benzemeyen durum kodları (A, 1, SUCCESS, Başarılı) tek bir sözlüğe indirgenir. Tanınmayan bir kod unknown döner — sessizce "başarılı" sayılmaz.

Ön provizyon isPaid() için false döndürür: tutar bloke edilmiştir ama tahsil edilmemiştir.

Ön provizyon

Bloke süresiz değildir; bankaya göre 1-30 gün içinde kapatılmazsa düşer.

Taksit ve BIN

BIN sorgusuna kart numarasının tamamını göndermeyin; ilk 6-8 hane yeter.

Tekrarlayan ödeme

Plan ilk ödemeyle birlikte bankaya bildirilir; sonraki çekimleri banka kendisi başlatır.

Desteklenen frekanslar bankaya göre değişir — Garanti yıllık, PayFlex haftalık tekrar sunmaz. supportedRecurringFrequencies() ile sorgulayın; desteklenmeyen bir frekans PaymentFailedException fırlatır.

Tutarlar

Tutarlar paket içinde her zaman kuruş cinsinden tam sayı olarak taşınır. 0.1 + 0.2 !== 0.3 olduğu için float ile hesaplanan bir tutar imzaya giren dizgiyi bir kuruş kaydırabilir ve banka işlemi reddeder.

float vermek çalışmaya devam eder — iki ondalık haneye yuvarlanıp kuruşa çevrilir. Tutarı zaten kuruş olarak tutuyorsanız (veritabanında int kolon gibi) Money::fromMinorUnits() kesinlik kaybı olmayan tek yoldur.

Driver'lar tutara yalnızca $data->money() üzerinden erişir ve bankanın istediği biçime orada çevirir:

Bankaların tuhaflıkları

Driver'lar bunları sizin için hallediyor. Burada olmalarının sebebi, bir şey ters gittiğinde nereye bakacağınızı bilmeniz.

Tutar formatı üç farklı. Garanti, PosNet, Kuveyt Türk ve Tosla kuruş cinsinden tam sayı ister (199.90 → 19990). NestPay ve PayFor PHP'nin doğal float gösterimini ister (199.9 → "199.9", 100.0 → "100"). Akbank POS ve PayFlex iki ondalıklı dizgi ister ("199.90"). Hash tam olarak gönderilen dizgi üzerinden hesaplandığı için bu formatlar değiştirilemez.

Taksit alanı tek çekimde bile dört farklı. NestPay boş dizgi, PosNet '00', PayFor ve Kuveyt Türk '0', Param '1' bekler. PayFlex alanı hiç göndermez.

Para birimi kodu her yerde ISO 4217 sayısal değil. Kuveyt Türk dört haneli kullanır (0949), PosNet V1 harf kısaltması (TL, US, EU).

PayFor aynı gün içindeki işlemi iade ettirmez. Gün sonu kapanmadan Refund denenirse banka V014 ("Bu işlem geri alınamaz, lütfen asıl işlemi iptal edin.") döndürür; aynı gün için cancel() kullanın. Kart hamiline para iadesi açısından ikisi aynı sonucu verir, sadece muhasebe kaydı farklıdır.

PayFlex'te enrollment adımı diğer uçlardan ayrışır. Provizyon ve sorgu istekleri prmstr alanında URL-kodlanmış XML ister; enrollment ise düz form alanı bekler. XML gönderilirse banka alanları hiç okumadan yanıltıcı bir 2030 Invalid expire date döndürür. Son kullanma tarihi de iki biçimdedir: enrollment YYMM, provizyon YYYYMM.

PayFlex 3D'de PaReq her zaman klasik bir 3DS bloğu değildir. BKM "GO Güvenli Öde" kurulumunda base64'ü, kendi kendini gönderen bir HTML sayfasıdır ve doğrulama sayfası ACSUrl'de değil o sayfanın form hedefindedir; ACSUrl'e POST edilirse banka "400 Hatalı İstek" sayfası verir. Driver bunu ayırt eder.

PayFlex 3D provizyonu kart bilgisi istemez. Banka işlemi MpiTransactionId üzerinden bulur; bazı kurulumlar kart gönderilmesini 1127 ile reddeder. Bu yüzden verify() çağrısında order['card'] isteğe bağlıdır — vermezseniz kart alanları hiç gönderilmez ve PAN'ı istekler arasında saklamanız gerekmez.

PayFlex durum sorgusu tek bir durum alanı döndürmez. IsCanceled, IsReversed, IsRefunded, TotalRefundAmount ve IsCaptured bayraklarından türetilir. Kısmî iade edilmiş bir işlem paid kalır; refunded yalnızca tamamı iade edildiğinde döner.

Garanti iade için ayrı kullanıcı ister. refund ve void işlemlerinde securityData normal şifreyle değil iade şifresiyle hesaplanır. İki ayrı kullanıcı tanımlamazsanız iadeler reddedilir.

PosNet üç sunucu isteği yapar. Önce oosRequestData ile veri paketleri alınır, sonra 3D geçidine POST edilir, dönüşte oosResolveMerchantData ile çözülüp oosTranData ile provizyon tamamlanır. Sipariş numarası 20 haneye sıfırla doldurulur; iade/iptalde 24 hane olur ve 3D siparişler TDSC ön eki alır.

Ziraat Katılım'ın dönüş hash'i banka tarafında tutarsız üretiliyor. Bu yüzden o preset'te verify_hash varsayılan olarak kapalıdır. Bankanız düzelttiyse ZIRAAT_KATILIM_VERIFY_HASH=true yapın.

PayTR ve Moka bildirimi OK yanıtı bekler. Webhook'unuz gövdede düz metin OK döndürmezse bildirim tekrar tekrar gönderilir (Moka iki kez daha dener).

Paratika iki hash alanı döndürür ve biri kullanımdan kalkmıştır. SD_SHA512 örnek yanıtlarda önce görünür ama dokümanda "Do not use!" işaretlidir; doğrusu sdSha512dir. Ayrıca durum sorgusu bir sipariş için tüm işlemleri döndürür; sadece satış kaydına bakarsanız iade edilmiş sipariş "ödendi" görünür.

Tosla zaman damgasını Türkiye saatinde ister. timeSpan GMT+3'te ve en fazla 1 saat farkla kabul edilir. UTC'de çalışan bir uygulamada damga üç saat geride kalır ve her istek 998 Validasyon Hatası alır — mesaj sebebi söylemez. Paket damgayı Europe/Istanbul üretir.

Moka'da üç ayrı kimlik vardır ve birbirinin yerine geçmezler:

Paket verdiğiniz değeri sipariş numaranız sayar; Moka'nın kendi kodunu kullanacaksanız metadata['virtual_pos_order_id'] ile bildirin. Biçime bakarak tahmin edilmez: kod dokümanda ORDER-… görünse de gerçek bir bayide Test-df91b14d-… biçiminde geldi.

Durum sorgusundan dönen paymentId DealerPaymentId'dir; onu iptal veya iadeye verirseniz PaymentNotFound alırsınız.

Moka'da durum sorgusu ödeme numarasını değil sipariş numaranızı ister. GetDealerPaymentTrxDetailList ucu OtherTrxCode (sizin sipariş numaranız) ya da PaymentId (Moka'nın sayısal kaydı) kabul eder. Dönüşteki trxCode bunların hiçbiri değildir — iptal ve iade için kullanılır.

Moka'da her banka her bayide tanımlı değildir. Sanal POS'u tanımlanmamış bir bankanın kartıyla ödeme başlatırsanız VirtualPosNotAvailable alırsınız. Hata kartın bankasıyla ilgilidir — tutar veya taksit değiştirmek çözmez.

Moka'da BIN sorgusu farklı bir sarmalayıcı ister. Diğer servisler PaymentDealerRequest, BIN sorgusu BankCardInformationRequest bekler. Paket bunu kendisi ayırır; kendi isteğinizi yazıyorsanız dikkat edin.

Moka başarıyı ayrı bir alanda söylemez. 3D dönüşündeki resultCode başarılı işlemlerde boş gelir; sonuç hashValue içindedir. Ödeme başlatılırken dönen CodeForHash saklanmazsa dönüş yorumlanamaz.

Param IP kısıtı uygular ve eski test adresi kapandı. posws ve testposws sunucuları whitelist dışındaki adreslerden gelen isteği WAF seviyesinde 403 ile reddeder — yani kimlik bilgileriniz doğru olsa bile sunucunuzun IP'si Param'a bildirilmeden hiçbir çağrı geçmez. Ayrıca çok sayıda kaynakta geçen test-dmz.param.com.tr adresi artık 404 dönüyor; güncel test adresi testposws.param.com.tr'dir.

⚠️ Param'ın (Türk Elektronik Para A.Ş.) altyapısı fiilen kapalı — IP kısıtı bunun bir sonucu, sebebi değil. TCMB 2026-04-30'da Param'ın ödeme hizmetleri ve e-para ihraç yetkisini geçici olarak durdurdu; 2026-05-04'te mahkeme yürütmeyi durdurunca şirket kesintisiz çalışmaya devam etti, ama 2026-07-13'te mahkeme bu kararı geri çekti ve TMSF, İstanbul Cumhuriyet Başsavcılığı soruşturması kapsamında Param ve grup şirketlerine kayyum olarak atandı. 2026-08-05 tarihli basın duyurusunda TMSF, ParamPOS üye işyeri alacaklarının 100.000 TL'ye kadarının ödeneceğini açıkladı — yani POS hizmeti normal işlemiyor, tasfiye/iade süreci işliyor. Bu durumdayken param driver'ını yeniden doğrulamaya çalışmak (yeni IP bildirmek, test üye işyeri istemek) anlamsız: muhatap kurumun kendisi kayyım denetiminde. Kod repoda kalıyor ama aktif olarak sürdürülmüyor.

Craftgate iki ayrı anahtar kullanır. API istekleri Secret Key ile, 3D dönüşü panelde ayrıca üretilen 3D Secure Callback Key ile imzalanır. İkisini karıştırmak "imza geçersiz" hatası verir. Webhook'ların üçüncü bir anahtarı vardır (Merchant Hook Key).

Craftgate'te ödeme formu POST edilmez. 3ds-init ucu hazır bir HTML sayfası döner; PaymentResponse::$htmlContent içinde gelir ve doğrudan tarayıcıya basılır. Ayrıca kısmi iade ödeme değil işlem bazındadır: metadata['payment_transaction_id'] vermezseniz paket sessizce tam iade yapmak yerine hata verir.

Taşıma hatalarında iki ayrı soru vardır. safeToRetry isteğin bankaya ulaşmadığından emin miyiz, outcomeUncertain ise işlemin gerçekleşmiş olma ihtimali var mı demektir. Banka isteği okumadan reddettiyse (4xx) sonuç kesindir — hiçbir şey olmamıştır; zaman aşımı ve 5xx'te ise durum sorgusuyla teyit gerekir.

Kuveyt Türk'te sorgu ve iade ayrı bir SOAP servisindedir. Ödeme ve provizyon XML uçlarına giderken durum sorgusu, iade ve iptal VirtualPosService.svc/Basic adresine gider. Bu uç JSON gövdeyi 415 ile reddeder ve paketin bu bölümü henüz doğrulanmamıştır. Ayrıca query_api tanımlanmazsa varsayılan canlı adrestir — test terminaliyle çalışırken mutlaka test adresini verin.

NestPay sorgu yanıtında tutarlar kuruş cinsindendir. Birleşik ORDERSTATUS alanındaki ORIG_TRANS_AMT ve CAPTURE_AMT kuruştur; ondalık sanılırsa tutar yüz katı raporlanır. Paket bunu ayırır.

NestPay dönüşünde boş alanlar null olmamalı. Banka boş alanları hash'e boş dizgi olarak katar. Laravel'in varsayılan ConvertEmptyStringsToNull middleware'i bunları null yapar; paket null'ı boş dizgi sayarak bunu telafi eder. Dönüş yükünü kendiniz işliyorsanız aynı kurala uyun, yoksa imza hiçbir zaman tutmaz.

Bankanın dönüş POST'u siteler arasıdır. SameSite=lax çerezi bu istekte gönderilmez; dönüşte oturum boş gelir. Sipariş bağlamını oturumda değil, okUrlin sorgu dizgisinde taşıyın. Doğrulamaya yalnızca POST gövdesini verin — sorgu parametreleri bankanın imzasına dâhil değildir.

NestPay hash'i alanları sıralar. Alanlar doğal sırada (harf duyarsız) sıralanır, hash/encoding/nationalidno çıkarılır, sona secret key eklenir, | ve \ karakterleri kaçırılır. Forma yeni bir alan eklerseniz hash'e de girer — banka bunu bilmiyorsa işlem reddedilir.

Hata yönetimi ve yeniden deneme

Ödeme entegrasyonlarında en tehlikeli hata, belirsiz olandır. Banka "reddettim" derse ne yapacağınız bellidir; ama istek zaman aşımına uğradığında paranın çekilip çekilmediğini bilmezsiniz. Paket bu ikisini tip düzeyinde ayırır:

TransportException yakaladığınızda ödemeyi başarısız saymayın — durumu banka üzerinden sorgulayın veya müşteriye "işleminiz kontrol ediliyor" deyin.

Yeniden deneme

Retry yalnızca bankaya ulaşılamayan durumlarda yapılır: bağlantı reddedildi, DNS çözülemedi, TLS kurulamadı. Bu hatalarda isteğin bankaya varmadığı bilinir.

Zaman aşımı ve HTTP hataları tekrar denenmez. Her ikisinde de istek bankaya ulaşmış ve işlenmiş olabilir; körlemesine ikinci bir ödeme isteği göndermek çift çekim demektir. Bu davranış testle kilitlidir.

Varsayılan 0dır — yani retry kapalıdır. Açmadan önce sipariş durumunu kendi tarafınızda takip ettiğinizden emin olun.

Event'ler

Ödeme akışının dört noktasında event yayınlanır. Hiçbiri kart verisi taşımaz, çünkü dinleyicilerin çoğu bu veriyi loglar veya kuyruğa yazar.

PaymentVerified success: false ile de gelebilir — bu, doğrulama akışının hatasız tamamlandığı ama ödemenin alınmadığı anlamına gelir. PaymentFailed ise akışın kesildiği durumdur; istisna yutulmaz, event'ten sonra yukarı çıkar.

ANADOLUPAY_EVENTS=false ile kapatılabilir.

Mükerrer ödeme koruması

Aynı sipariş numarası için pencere içinde ikinci bir createPayment() çağrısı DuplicatePaymentException fırlatır. Asıl hedef kullanıcının "Öde" düğmesine iki kez basmasıdır.

Pencere bilinçli olarak kısadır (varsayılan 30 sn): ödeme gerçekten başarısız olduğunda müşterinin aynı sipariş numarasıyla tekrar denemesi meşrudur. Başlatma isteği hata alırsa kilit hemen bırakılır.

Kilit Cache::add() ile alınır — atomiktir, yani iki eşzamanlı istekten yalnızca biri geçer. Bunun çalışması için array dışında bir cache sürücüsü (redis, memcached, database) gerekir.

Bu bir kolaylıktır, kesin garanti değildir. Mükerrer çekime karşı asıl savunma, siparişin durumunu kendi veritabanınızda tutmak ve ödemesi alınmış siparişler için akışı hiç başlatmamaktır.

Loglama

Banka bir işlemi reddettiğinde size yalnızca bir kod döner (ProcReturnCode=99). Sorunun hangi alanda olduğunu ancak gönderdiğiniz gövdeyi görerek anlarsınız. Entegrasyon geliştirirken açın:

Maskeleme iki katmanlıdır. Birincisi alan adına göre (cvv, password, secret_key…). İkincisi değerin biçimine göre: Luhn kontrolünden geçen her 13–19 haneli sayı, alan adı ne olursa olsun maskelenir. İkinci katman olmadan, on altı driver'ın farklı adlandırdığı kart alanlarından birini gözden kaçırmak kart verisini loga düşürürdü.

Luhn kontrolü yanlış pozitifleri de eler — PosNet'in 20 haneye doldurulmuş sipariş numaraları ve NestPay'in MD taşıyan Number alanı okunabilir kalır.

Başarısız HTTP yanıtları warning, gerisi debug seviyesindedir.

Loglama varsayılan olarak kapalıdır. Maskeleme uygulansa bile bu kayıtların nereye yazıldığı bilinçli bir tercih olmalıdır: kalıcı bir kanal seçiyorsanız erişimini kısıtlayın ve saklama süresi tanımlayın.

iyzico

iyzico bankalardan iki noktada ayrılır ve paket ikisini de sizin yerinize halleder:

• 3D adımında form alanı değil, base64 kodlanmış hazır bir HTML sayfası döner. Paket bunu çözer; toHtmlForm() doğrudan basılabilir HTML verir.
• Her yanıt, callback ve webhook ayrı bir imza şeması kullanır. Üçü de HMAC-SHA256 üretir ve sonucu onaltılık kodlar:

Yanıt imzasında alan sırası uca göre sabittir; örneğin 3DS callback'i conversationData:conversationId:mdStatus:paymentId:status sırasını kullanır. Tutarlardaki sondaki sıfırlar imzadan önce atılır (10.50 → 10.5).

İade /v2/payment/refund ucundan yapılır:

iyzico'da tutar zorunludur. Diğer driver'larda tutarı boş bırakmak "tamamını iade et" demektir; iyzico'da böyle bir uç yoktur ve tutarsız istek 5004 price gönderilmesi zorunludur ile reddedilir. Paket bu durumda ödemenin tutarını /payment/detail ucundan okuyup gönderir — yani tutarsız çağrı da çalışır, ama arka planda fazladan bir sorgu yapar.

Kısmi iade yapılmış bir ödemede okunan tutar kalan bakiyeden büyük olur ve iyzico işlemi reddeder. Bu bilinçli bir tercihtir: fazla iade etmektense hata vermek doğrudur. Öyle bir ödemede tutarı açıkça verin.

Ayrı bir iptal işlemi yoktur. Driver SupportsCancellation uygulamaz; çünkü iyzico aynı gün yapılan tam iadeyi kendisi iptal olarak işler — yanıtta transactionType: CANCEL döner. Gün içi iptal için refund() çağırın.

Paratika

Paratika, NestPay driver'larının arkasındaki Payten/Asseco'nun kendi ödeme kuruluşudur. İstek imzası kullanmaz; kimlik doğrulama her isteğe eklenen üç alandır. İmza yalnızca 3D dönüşünde vardır.

Akış her modelde bir oturum anahtarıyla başlar. Paket bunu sizin yerinize yapar; dört ödeme modeli dört farklı uca karşılık gelir:

Dönüş imzasında iki alan gelir ve biri tuzaktır. Örnek yanıtlarda SD_SHA512 önce görünür ama dokümanda "Deprecated / Legacy — Do not use!" diye işaretlidir. Paket güncel olanı doğrular:

PARATIKA_SECRET_KEY, API şifresinden farklı bir değerdir.

Durum sorgusu bir liste döndürür. Paratika bir sipariş numarasına ait tüm işlemleri verir: satış, iade, iptal. İade edilmiş bir satışın kendi kaydı hâlâ AP (onaylı) görünür — tek kayda bakan entegrasyon iade edilmiş siparişi "ödendi" sanır. Paket listenin tamamını yorumlar: tam iade refunded, kısmi iade paid + refundedAmount, iptal cancelled.

İade tutarı verilirse Paratika bunu kendi tarafında PTREFUND olarak kaydeder; ayrı bir aksiyon göndermeniz gerekmez.

Moka United

Moka'nın kimlik doğrulaması bir istek imzası değil, sabit bir paroladır:

Her istekte aynı değer gider — yani gövdeyi korumaz. Bu paketin diğer driver'larındaki hash'lerden farkı budur.

Asıl dikkat edilmesi gereken yer 3D dönüşü. Moka ödemenin başarılı olup olmadığını ayrı bir alanda söylemez; dönüşteki resultCode başarılı işlemlerde boş gelir. Sonuç yalnızca hashValue içinde taşınır:

CodeForHash ödeme başlatılırken bir kez döner. Saklamazsanız dönüşü yorumlayamazsınız — bu yüzden paket sonucu tahmin etmeye çalışmaz, hata verir:

Dönüşte:

Hash ne T ne F varyantıyla eşleşiyorsa InvalidSignatureException atılır.

İptal ve iade ayrı uçlardır ve aynı şey değildir. Aynı gün saat 22.00'ye kadar cancel() (DoVoid) işlemi anında iptal eder. refund() (DoCreateRefundRequest) ise bir iade talebi oluşturur: yanıtta RefundRequestId döner, ödemenin durumu hemen değişmez ve RefAmount bir süre 0 kalır. Gerçek test servisinde ölçüldü — talep başarıyla kabul edildikten sonra sipariş hâlâ paid görünüyordu.

Yani refund() başarılı dönmesi "para geri gitti" demek değil, "talep alındı" demektir. Aynı gün geri ödeme istiyorsanız cancel() kullanın. İade tutarı verilmezse kalan tutarın tamamı talep edilir.

Referans olarak hem Moka'nın numarası hem sizinki kullanılabilir; paket ORDER- ile başlayan değerleri Moka'nın numarası (VirtualPosOrderId), diğerlerini kendi sipariş numaranız (OtherTrxCode) sayar.

Moka da PayTR gibi bildirimlere düz metin OK yanıtı bekler; paketin webhook rotası bunu kendisi döndürür.

Craftgate

Craftgate tek bir bankanın sanal POS'u değil, birden çok POS'u tek API arkasında toplayan bir orkestrasyon platformudur. Akış bu yüzden banka driver'larından ayrılır: müşteri bir banka geçidine form POST edilmez, 3ds-init ucu hazır bir HTML sayfası döner.

Üç ayrı anahtar kullanılır; hangisinin nerede kullanıldığını karıştırmak en sık yapılan hatadır:

Webhook imzasını driver doğrular:

Kısmi iade işlem bazındadır. Craftgate bir ödemeyi birden çok satıcı işlemine bölebildiği için hangi işlemin iade edileceğini paket kendi başına seçemez:

payment_transaction_id vermezseniz paket sessizce tam iade yapmaz, hata verir. Tam iade için tutarı hiç göndermeyin. Gün içi iptal ayrı bir uç değildir; Craftgate mutabakata girmemiş işlemi iade isteğinde kendisi void olarak geçer.

Tami

⚠️ Henüz gerçek bir sandbox'a karşı doğrulanmadı. Aşağıdaki üç nokta dokümantasyondan (dev.tami.com.tr) çıkarıldı ama test edilmedi — sandbox kimlik bilgisi elinize geçtiğinde ilk iş bunları doğrulamak olmalı.

Tami de Craftgate gibi bir orkestrasyon platformu; /payment/auth ucu 3D başlatmayı ve non-secure satışı birlikte karşılar, 3D doğrulaması banka callbackUrl'e POST ettiğinde ise para ayrı bir /payment/complete-3ds isteğiyle çekilir:

İki katmanlı kimlik doğrulama:

Bilinen sınırlar:

• securityHash için JWT/JWS yorumu, dokümantasyonun "Security Hash Hesaplama" sayfasındaki somut kod örneğine (JWSObject/MACSigner) dayanır. Ama diğer sayfalardaki örnek securityHash değerleri nokta içermiyor — düz bir HMAC digest'i gibi görünüyor, JWT gibi değil. Dokümantasyon bu noktada kendi içinde çelişkili.
• Ön provizyon kapama ucu (/payment/post-auth) doğrulanmadı; /payment/pre-auth ile aynı adlandırma kalıbından tahmin edildi.
• 3D dönüş callback'inin imzası (hashedData = base64(hmac_sha256( cardOrganization+cardBrand+cardType+maskedNumber+installmentCount+ currencyCode+txnAmount+orderId+systemTime+success, secretKey))) Tami'nin kendi dokümantasyonunda formülsüz bırakılmıştı; alan sırası ve anahtar bağımsız bir kaynaktan doğrulandı — Tami'nin resmî bir onayı değil, gerçek bir sandbox'a karşı hâlâ test edilmedi.
• İptal (cancel) ve iade (refund) dokümantasyonda aynı uca (/payment/reverse) gidiyor; ikisi arasında protokol seviyesinde bir fark bulunamadı.

Test ortamı

Test kartları için ayrı bir belge var: TEST-KARTLARI.md — iyzico, Garanti, Akbank, PayTR, Craftgate, Moka ve Paratika'nın listeleri (hata senaryosu kartları dahil), diğer bankalar için kartı nereden alacağınız. Her bölümde hangi kartla ölçüm yaptığımız ve hangisinden kaçınmanız gerektiği yazılıdır.

Preset'lerdeki uç noktalar canlı ortamı gösterir. Test için ilgili *_PAYMENT_API / *_GATEWAY_3D değişkenlerini bankanızın test adresiyle değiştirin ve *_TEST_MODE=true yapın.

Garanti, çoğu bankanın aksine test üye işyeri bilgilerini geliştirici portalında açıkça yayınlar — bankadan ayrıca bir şey istemeniz gerekmez. Bu değerlerle çalıştığı 2026-08-11'de doğrulandı:

Ödeme ve iade iki ayrı kullanıcı ister (PROVAUT / PROVRFN); test ortamında ikisinin şifresi de aynıdır. Test yönetim paneli sanalpostest.garanti.com.tr adresinde: kullanıcı 99999999999, parola Destek.9, şifre 147852.

Bu terminalde iade ve iptal banka tarafından reddedilir (05 / RPC-05); ön provizyon da 14 verir. Driver'ın hatası değildir — istek biçiminin on dört ayrı çeşitlemesi (tam/kısmi tutar, OriginalRetrefNum ile ve olmadan, void/refund) aynı yanıtı verir, terminalde bu yetkiler tanımlı değildir.

Sahte driver

Gerçek istek atmadan akışı denemek için fake driver'ını kullanın. Gerçek driver'ların yetenek arayüzlerini uygular ve yaptığı işlemleri bellekte tutar — ödeyip sonra status() sorarsanız gerçekten paid döner, iade ederseniz refunded olur.

Varsayılan olarak her işlem başarılıdır; testlerin rastgele kırılmaması için sahte geçidin öngörülebilir olması gerekir. Hata yollarını denemek isterseniz:

Gerçek kartlarla denemek isterseniz TEST-KARTLARI.md.

Güvenlik

• Kart verisi (CardData) saklanmamalıdır. Kendi loglarınızda göstermeniz gerekiyorsa CardData::masked() kullanın; paketin istek/yanıt logları zaten maskelidir.
• CardData nesnelerini dd(), var_dump() veya exception raporlarına vermeyin — bunlar maskelemeden geçmez.
• verify_hash yalnızca bankanın hash'i tutarsız ürettiği bilinen kurulumlarda kapatılmalıdır. Kapalıyken sahte callback'lere açıksınızdır.
• verify_ssl her zaman true kalmalıdır.
• 3D Host modeli kart verisini sunucunuzdan tamamen uzak tutar; PCI kapsamını daraltmak istiyorsanız en iyi seçenektir.

Güvenlik açığı bildirimi: [email protected]

Yeni banka eklemek

AbstractBankGateway sınıfını genişletin ve yedi metodu implement edin:

Sonra config/anadolupay.php içindeki banks dizisine bir preset ekleyin. Akış, hata yönetimi, HTTP ve loglama temel sınıftan gelir.

İmza için test yazın. Sabit girdilerle üretilmiş bir özet değerine kilitleyin — mevcut driver'ların hepsinde örneği var (tests/Bank/HashTest.php). İmza sessizce bozulabilen tek şeydir.

Yol haritası

Bilinen eksikler. Bir maddeye başlamadan önce issue açmanız çakışmayı önler.

Öncelikli

• [x] iyzico imza şemasını doğrula. Üç şema da (Authorization, yanıt/callback, webhook) resmi dokümantasyondan teyit edilip düzeltildi ve testle kilitlendi.
• [x] iyzico iadesi. /v2/payment/refund ile tam ve kısmi iade.
• [x] Tutarları kuruş cinsinden tam sayıya taşı. Money value object; float girdi geriye dönük uyumlu olarak destekleniyor.

İşlem kapsamı

• [x] cancel() ve status()'ü sözleşmeye taşı. Yetenekler artık arayüzlerle bildiriliyor — bkz. Yetenekler.
• [x] Eksik cancel(). Kuveyt Türk (ayrı SOAP servisi) ve Param eklendi. PayTR iptal API'si sunmuyor; sağlayıcı sınırı.
• [x] Eksik status(). 13 driver'a yayıldı. Akbank POS tekil durum sorgusu sunmuyor; yerine işlem geçmişi var.
• [x] Kuveyt Türk iade/iptal.
• [x] Ön provizyon / provizyon kapama. 12 driver.
• [x] İşlem geçmişi, taksit oranı ve BIN sorgulama.
• [x] Tekrarlayan ödeme. Asseco, Garanti, PayFlex, Akbank POS.

Doğrulama

• [x] iyzico uçtan uca doğrulaması. 2026-08-09, sandbox 3D Secure satış: dört imza şeması da gerçek trafikle doğrulandı. Bkz. Doğrulama durumu.
• [x] İlk banka terminali. Ziraat NestPay test terminalinde 3D hash'i ve API kimlik doğrulaması kabul edildi; durum sorgusunda bulunan bir kusur düzeltildi.
• [x] NestPay'de 3D akışını tamamla. 2026-08-09, Ziraat test terminali: tarayıcıdan 3D onayı, provizyon, durum sorgusu, iade ve iptal. Üç kusur çıktı (hash'te null işlenmesi, bileşik ORDERSTATUS, kuruş tutar).
• [x] PayFlex için gerçek terminal testi. 2026-08-10, VakıfBank'ın açık sandbox'ı: 3D Secure satış, non-3D satış, durum, iade, iptal, ön provizyon ve kapama. Dört kusur çıktı — bkz. CHANGELOG.
• [ ] Kalan altyapılar için gerçek terminal testi — Garanti, PosNet, PayFor, InterPos. BOA'da yalnızca ödeme doğrulandı (Kuveyt Türk); sorgu/iade servisi SOAP olduğu için ölçülemedi. Kapsamı yatay büyütmek bu doğrulama yapılmadan riski azaltmıyor.
• [x] iyzico'nun işlem kapsamı. İade, durum, BIN ve taksit sorgusu sandbox'ta doğrulandı; iade tutarsız çağrıda hiç çalışmıyordu, düzeltildi. İptal ayrı bir işlem değil — iyzico tam iadeyi iptal olarak işliyor.
• [ ] iyzico'nun diğer ödeme modelleri (3d_pay, 3d_host, regular) sandbox'ta çalıştırılmadı.

Yeni bankalar

Çoğu mevcut NestPay driver'ını kullanır; yeni kod değil, preset ve doğrulanmış uç nokta gerekir.

• [x] ING · Alternatif Bank · Türkiye Finans. Üçü de NestPay kullanıyor; uç noktaları doğrulandı (aşağıya bakın).
• [ ] Anadolubank · Odeabank · Fibabanka · Burgan Bank · Emlak Katılım — sanal POS uç noktaları herkese açık bir kaynaktan doğrulanamadı. Tahmin edilen alan adları ya DNS'te yok ya da NestPay/PayFor/BOA imzası vermiyor. Bu bankalardan biriyle çalışıyorsanız entegrasyon dokümanınızdaki adresi issue olarak paylaşın, preset'i ekleyelim.

Preset eklenmemiş olması o bankayla çalışamayacağınız anlamına gelmez: altyapısı bilinen bir bankanın uç noktalarını config/anadolupay.php içinde kendiniz tanımlayabilirsiniz — bkz. Yeni banka eklemek.

Yeni ödeme kuruluşları

• [x] Craftgate. API imzası, 3D dönüş imzası ve webhook imzası Craftgate'in resmi istemci depolarındaki test vektörleriyle doğrulandı.
• [x] Moka United. Dokümantasyonu tamamen açık; dönüş hash'i oradaki test vektörüyle kilitlendi.
• [x] Paratika (Payten). Dokümantasyonu ve resmî örnek kodu açık. Test vektörü yayınlanmadığı için imza formülü dokümana göre uygulandı, ölçülmedi.
• [x] Paycell. Eklendi. Resmî doküman bu arada yayımlandı (paycellapi.apidog.io); test kimlik bilgileri ve kart listesi herkese açık. Kart token adımı ve yanıt imzası sağlayıcının test ortamına karşı ölçüldü, 3D oturumu açıldı. Ödeme adımı ortak test üye işyerinde Bank error verdiği için doğrulanamadı — kendi üye işyeri kodunuzla denenmeli.
• [ ] Sipay — imza şeması güvenilir bir public kaynaktan doğrulanamadığı için bilinçli olarak eklenmedi.
• [ ] PayU Türkiye — eklenmeyecek. PayU'nun Türkiye'deki ödeme ucu (secure.payu.com.tr) artık DNS'te yok; PayU Türkiye'de iyzico markasıyla çalışıyor. İhtiyacınız olan driver iyzico.
• [ ] Vallet

Altyapı

• [x] PSR-3 loglama (maskeli) — bkz. Loglama
• [x] Event'ler — bkz. Event'ler
• [x] Idempotency — bkz. Mükerrer ödeme koruması
• [x] Retry politikası — bkz. Hata yönetimi ve yeniden deneme
• [x] Hata sınıflandırması — TransportException ile PaymentFailedException artık ayrı; aynı bölüme bakın.

Katkı

Detaylar için CONTRIBUTING, sürüm geçmişi için CHANGELOG.

Lisans

MIT — bkz. LICENSE.