Sanal POS Rehberi: Başvurudan İlk Gerçek Çekime — Atlas

Bu rehberin sonunda: sağlayıcı tekliflerini efektif maliyete çevirir, başvuru dosyanı bankanın gözüyle hazırlar, panel kimlik tuzaklarını bilir ve ilk gerçek tahsilatını denetimli bir hata-avı disipliniyle canlıya alırsın.

📅 Son tarama: 4 Eylül 2026. Komisyonlar, panel ekranları ve banka kuralları değişir; sondaki istemle tazele.

Bu dosyanın rolü: arac-envanteri "hangi altyapıyı seçtik"i anlatır; burası o ailenin en az yazılan üyesini anlatır: kendi ürününe kart ödemesi almak. Temmuz–Eylül 2026'da SoloLabs'ın banka sanal POS'u kurulumunun tamamı — sağlayıcı yarışı, bir başvuru reddi, kimlik tuzağı ve 6 denemelik hata avı dahil — gerçek rakamlarla bu rehberin içindedir. Hata avı disiplini için kardeşi: prod-vakalari.

Kapsam: tek çekim (kredi paketi, aylık paket satışı). Abonelik (recurring) ve pazaryeri ödemesi bu rehberin sonunda "bilinçli sınır" olarak işlenir: banka POS'u ikisini de YAPMAZ; gerekiyorsa PSP katmanı planlanır.

---

1 · Sağlayıcı kararı: komisyon tek başına yalan söyler

Teklifler tek sayıyla gelir ("%X komisyon") ama gerçek maliyet dört kalemdir:

Efektif maliyet = komisyon + valörün para maliyeti + işlem ücreti + aidat

Valör = paranın hesabına geçme süresi. 30 gün valör, paranın 30 gün başkasında durması demektir; işletme kredisi faiziyle (2026'da KMH ~%58/yıl) çarpınca gizli bir komisyona dönüşür.

Gerçek teklif tablosu (SoloLabs, Ağu 2026 — teklifler firmaya ve döneme göre değişir):

Ders 1: Ödeme kuruluşları yeni firmaya "risk primi" koyar — aynı firmanın kamu ilanı ile sana verdiği teklif 2 kat farklı olabilir. Banka POS'u bu vakada 4-6 kat ucuz çıktı.

Ders 2 (sınır): Banka POS'u recurring yapmaz ve üçüncü kişiye para dağıtmaz. Aboneliğin ya da pazaryerin varsa PSP tamamlayıcı katmandır; "hangisi" değil "hangi işe hangisi" sorusudur.

🪞 Denetim penceresi: Ajanına "şu 3 teklifi efektif maliyete çevir" dedirt; valör × para maliyeti kalemini atlıyorsa hesap eksiktir.

2 · Başvuru dosyası: bankanın gözüyle siten

Gerçek red, gerçek sebep: ilk başvuru ürün sitesinin (JS ile çizilen SPA) linkiyle yapıldı → RED — "sitede fiyatlar görünmüyor."

Banka inceleyicisi siteni senin gördüğün gibi görmez:

• Fiyatlar açık ve KDV dahil görünmeli — fiyatsız vitrin, incelemede boş sayfadır.
• JS'siz de içerik görünmeli (curl ile kendi sitene bak). SPA ise statik bir fiyat sayfası aç.
• 6 yasal sayfa: künye (VKN, adres, iletişim) · mesafeli satış · ön bilgilendirme · KVKK · iade/cayma · gizlilik.
• Satıcı kimliği = fatura kesen tüzel kişilik. Sitedeki unvan ile başvurudaki unvan aynı olmalı.
• SaaS satıyorsan checkout'ta iki onay kutusu: mesafeli satış + anında ifa/cayma istisnası (Mesafeli Sözleşmeler Yönetmeliği md. 15/1-ğ — RG 27.11.2014/29188: elektronik ortamda anında ifa edilen hizmetler).

Çözüm bu vakada pay.sololabs.com.tr oldu: saf statik HTML, en üstte iki lokomotif ürünün tam fiyat kartı, altı yasal sayfa. Karar cümlesi aynen: "10-15 ürün onayı artırmaz; 2-3 ürün sağlam ve fiyatlı görünsün, gerisi sonra bağlanır."

3 · Onay maili ve panel: kimliklerin TEK kaynağı

Onay maili dört kimlik verir ve bu rehberin en pahalı dersi şudur: kimlikleri panel ekranından değil onay mailinden al.

Panel kurulum sırası (Kuveyt Türk örneği; diğer bankalarda adlar değişir, mantık değişmez):

1. API rolünde kullanıcı aç: ad ≤10 alfanumerik, şifre ≥8 büyük/küçük/rakam, Aktif = Evet (varsayılan Hayır'dır — ilk sessiz tuzak).
2. IP tanımı: sunucunun çıkış IP'leri panele girilir. Tanımsız IP'den istek PosMerchantIPError döner.
3. SMS/Link ile ödeme: kod yazmadan ilk gerçek tahsilat — entegrasyonu beklemeden nakit akışı başlar.
4. Dokümantasyon ekranı: güncel entegrasyon PDF'i ve cevap kodları buradan indirilir (birincil kaynak budur; herkese açık URL'i yoktur).

4 · Sabit çıkış IP'si = aslında bir hosting kararı

Banka "isteklerin şu IP'lerden gelsin" der; serverless platformlarda ise sabit çıkış IP'si çoğu zaman yoktur. Bu tek satır, ödeme servisinin nerede yaşayacağını belirler:

İki tuzak: static IP açılınca yeniden deploy gerekir (eski konteyner eski IP'den çıkar) ve IP'yi panele girmeden önce konteynerin içinden doğrula (fetch('https://api.ipify.org')) — platform panelindeki IP listesi ile konteynerin gerçek çıkışı farklı olabilir.

5 · Entegrasyon mimarisi: bir kez entegre et, ürünlere dağıt

11 ürüne kart ödemesi almak, 11 banka entegrasyonu demek değildir:

• Merkezi ödeme servisi: banka entegrasyonu tek serviste (checkout. alt alanı). Ürünler HMAC imzalı istekle sipariş açar, kullanıcıyı checkout'a yönlendirir, dönüşte sunucudan sipariş sorgusuyla doğrular. 🔴 Tarayıcıdan gelen status=paid parametresine güvenilmez — bu, prod-vakalari'ndaki "istemciye güven" hatasının ödeme sürümüdür.
• Sağlayıcı adaptörü: init / handleCallback / refund arayüzü + PAYMENT_PROVIDER env. Kimlik yoksa notConfigured dönülür; uydurma akış yok.
• 3D Secure iki-istek akışı (KT 3D Model örneği): (1) XML istek → banka HTML döner → tarayıcıya basılır (3D şifre ekranı); (2) banka OkUrl/FailUrl'e AuthenticationResponse POST eder (UrlEncoded XML — form decode'dan sonra bir kez daha decode) → ResponseCode=00 ise MD değeriyle provizyon isteği → 00 OTORİZASYON VERİLDİ = para çekildi. 1. adımın geçmesi 2.'yi garanti etmez (aşağıdaki vakaya bak).
• Hash'leri dokümandaki örnek değerlerle birim testle. Formül base64(sha1(...)) + ISO-8859-9 gibi ayrıntılar elle doğrulanamaz; doküman örnekleri hazır test vektörüdür.
• PCI gerçeği: banka iFrame'i yasakladıysa kart verisi SENİN sunucundan geçer. Kart alanları log'a ve DB'ye asla yazılmaz, yalnız bellekte tutulur; teşhis logu kart alanlarını maskeler.
• Sipariş durum makinesi + idempotency: created → awaiting_payment → paid/failed; aynı MD/sipariş iki kez işlenmez; ProvisionNumber/RRN/Stan iade ve mutabakat için saklanır.

6 · ⚠ GERÇEK VAKA: InvalidMetaData avı (4 Eyl 2026, 20:00–21:02)

Senaryo: Canlıda 2₺'lik denemeler. 1. adım her seferinde 00 Kart doğrulandı; 2. adım her seferinde InvalidMetaData: MD değeri ile gönderdiğiniz değerler uyumsuzdur. Para hiç çekilmiyor.

Teşhis (her denemede TEK değişken):

Çözüm: CustomerId = onay mailindeki Müşteri No. Paneldeki "Müşteri No" sütunu mağaza numarasını gösteriyordu; tek yanlış satır dört başarısız canlı denemeye mal oldu.

Kalıcı dersler:

1. 1. adımın geçmesi kimliklerin doğru olduğunu KANITLAMAZ — banka bazı alanları ancak provizyonda kıyaslar.
2. İki başarısız denemeden sonra kör denemeyi durdur; her denemenin tek değişkeni ve yazılı kanıtı olsun.
3. Kimlikleri panel etiketlerinden değil onay mailinden al; arayüz etiketi yanıltıcı olabilir.
4. Üretimde çalışan açık-kaynak entegrasyonla alan alan kıyas, dokümandaki örnekten değerlidir.
5. Teşhis logu (kart verisi maskeli) baştan olsun; banka cevabının tamamını görmeden hipotez kurma.

Hızlı sınav: Banka 2. adımda "değerler uyumsuz" diyor ama 1. adım geçiyor. İlk bakacağın yer (a) hash formülü (b) alan sırası (c) kimliklerin geldiği kaynak (d) tutar biçimi? (c — değer kaynağı; bu vakada onay maili ile panel çelişiyordu.)

7 · Canlıya alma ve sonrası

• Gerçek doğrulama = 2₺ gerçek çekim + panelden iade. Test ortamları bulut IP'sine kapalı ya da test kartı bayat olabilir (bu vakada ikisi de öyleydi); küçük gerçek çekim en dürüst testtir.
• Başarısız senaryoları da test et: yanlış CVV, 3D ekranından vazgeçme.
• Sonuç sayfası iki hâlde de konuşsun: "Ödemeniz alındı" + ürüne otomatik dönüş / "alınamadı" + tekrar dene.
• Her paid siparişe fatura; mutabakat için banka referansları raporlanabilir olsun.
• Bankaya sor: saklı kart / tekrarlayan tahsilat var mı? Yoksa abonelik için PSP katmanı ayrı karar.

Sıfırdan canlıya kontrol listesi

• Tahsilat türleri yazıldı (tek çekim / recurring / payout) — recurring/payout varsa PSP planı
• ≥3 teklif alındı, hepsi efektif maliyete çevrildi
• Banka-yüzü site: fiyat KDV dahil + künye + 6 yasal sayfa + JS'siz görünürlük (curl testi)
• Onay maili kimlikleri secret kasasına — repoya asla; Mağaza No ≠ Müşteri No ayrı ayrı
• API rolünde kullanıcı (Aktif=Evet) + panel şifresinden farklı şifre
• Çıkış IP'si konteyner içinden doğrulandı → panele girildi → yeniden deploy
• Hash'ler doküman örnekleriyle birim testli; tutar kuruş; iFrame yok
• Kart verisi yalnız bellekte; loglar maskeli; idempotency var
• Ürünler imzalı sipariş sorgusuna güveniyor, tarayıcı parametresine değil
• 2₺ gerçek çekim 00 + iade ekstrede görüldü; başarısız senaryolar test edildi
• Sonuç sayfası + fatura + mutabakat referansları

Kopyalanabilir istemler

Sağlayıcı kıyası:

Şu sanal POS tekliflerini efektif maliyete çevir. Formül: komisyon + (valör gün / 365 × yıllık para
maliyeti %58) + işlem ücreti + aidat/aylık ciro. Teklifler: [buraya yapıştır]. Tabloyla sırala;
recurring ve payout ihtiyacım [var/yok] — banka POS'unun bu ikisini yapmadığını hesaba kat.

Başvuru sitesi denetimi:

Şu siteyi bir banka sanal POS inceleyicisi gözüyle denetle: [URL]. Kontrol et: (1) fiyatlar JS'siz
görünüyor mu (curl çıktısına bak), (2) KDV dahil mi, (3) künye/VKN/adres var mı, (4) 6 yasal sayfa
linkli mi, (5) sitedeki unvan başvurudaki tüzel kişilikle aynı mı. Eksikleri madde madde ver.

Hata kodu çözümleme:

Banka sanal POS cevabı: [kod + mesaj]. Bu koda üç olası neden hipotezi kur, her biri için TEK
değişkenli bir deneme öner ve hangi kanıtı toplayacağımı söyle. İki denemeden sonra durup kanıt
değerlendirmeden yenisini önerme. Kimlik alanları için önce onay mailini kaynak göster.

Kaynaklar

• Bankanın entegrasyon dokümanı (birincil) — panel → Yönetim → Dokümantasyon'dan indirilir; hash örnek değerleri ve cevap kodları oradadır. Herkese açık URL'i yoktur, güncelini her zaman panelden al.
• mewebstudio/pos (ikincil) — TR bankaları için açık kaynak PHP entegrasyonları; üretimde çalışan alan adları/istek yapılarıyla kıyas için (vakada 3. denemenin referansı).
• Mesafeli Sözleşmeler Yönetmeliği (RG 27.11.2014/29188), md. 15/1-ğ (birincil, mevzuat) — anında ifa edilen elektronik hizmetlerde cayma istisnası; SaaS checkout onay kutusunun dayanağı.

(Sağlayıcı teklif rakamları SoloLabs'a Ağustos 2026'da verilen tekliflerdir; kamuya ilan edilen güncel tarifelerle birebir örtüşmeyebilir — kendi teklifini kendi tarihinle kıyasla.)

🔄 Bu rehberi güncelleme istemi

sanal-pos.md dosyasını tazele: (1) komisyon/valör rakamları ve KMH oranı güncel mi — güncel teklif ya da
ilan bulamadığın kalemi "teyitsiz" işaretle; (2) panel adım adları hâlâ doğru mu (yeni ekran görüntüsü
varsa playbook klasöründen kıyasla); (3) recurring/saklı kart sorusunun cevabı geldiyse 7. bölümü ve
kapsam satırını güncelle; (4) yeni banka cevap kodu ya da tuzak yaşandıysa GERÇEK VAKA formatında ekle.
Tarih damgasını güncelle ve neyin değiştiğini tek satır yaz.