# FAZ 3a — Para Mimarisi (Havuz Hesabı Modeli) Karar: **para kendi havuz hesabımızda tutulacak.** Bu doküman o kararın hukuki dayanağını, mimari sonuçlarını ve veri modelini kuruyor. --- ## 1. Hukuki dayanak — istisna var, ama şartlı Havuz hesabında başkasının parasını tutup dağıtmak, kural olarak **ödeme hizmeti**dir ve 6493 sayılı Kanun kapsamında TCMB yetkilendirmesi gerektirir. Ama senin modelin için bir istisna mevcut. **6493 sayılı Kanun m.12/2-b — Ticari Temsilci İstisnası.** TCMB'nin kendi rehberindeki ifadeyle: *ödeme işleminin, gönderen ya da alıcı namına mal veya hizmet pazarlığına ya da alım satımına yetkili olan ticari temsilci aracılığıyla yapılması* ödeme hizmeti sayılmıyor. Sektörde bu istisnanın adı zaten **"pazaryeri iş modeli"**. Yani yapmak istediğin şey istisnanın ders kitabı örneği. Kötü haber değil. ### Ama üç şartı var **Şart 1 — Satıcı sözleşmesi sana ticari temsilci yetkisi vermek zorunda.** İstisna, "para tuttuğun için" değil, "satıcı namına satış yapmaya yetkili olduğun için" işliyor. Satıcı sözleşmesinde açık bir tahsil ve satış vekâleti bulunmazsa istisna düşer ve lisanssız ödeme hizmeti sunmuş olursun. **Bu maddeyi avukatın yazmalı**, şablon sözleşmeden kopyalanacak bir şey değil. **Şart 2 — Yıllık 50 milyon TL eşiği ve TCMB bildirimi.** Son on iki ayda istisna kapsamındaki işlem tutarı 50 milyon TL'yi aşarsa, her yıl **Ocak ayı içinde** TCMB'ye bildirim yapmak zorunlu. Buradaki "işlem tutarı" tanımı kritik ve çoğu kişi yanlış hesaplıyor: TCMB rehberine göre bu tutar, **komisyon dahil toplam satış bedeli** — yani GMV. Komisyon mahsup edildikten sonra satıcıya aktarılan net tutar değil. 50 milyon TL GMV, orta ölçekli bir pazaryeri için birinci yılda ulaşılabilir bir seviye. > **Yazılım sonucu:** GMV'yi kayan 12 ay penceresinde ölçen bir gösterge gerekiyor. > Eşiğe yaklaşınca uyarı vermeli. Bunu sonradan elle hesaplamaya kalkmak istemezsin. **Şart 3 — TCMB istisnayı geri alabilir.** Kanun değişikliğiyle TCMB'ye, istisna kapsamındaki faaliyetleri belirli bir etki alanı veya işlem hacmine ulaştıklarında **ödeme hizmeti olarak yeniden değerlendirme** yetkisi verildi. Yani istisna kalıcı bir muafiyet değil, ölçek büyüdükçe kapanabilen bir kapı. Pratik anlamı: mimariyi, ileride lisanslı bir ödeme kuruluşuna geçiş yapabilecek şekilde kurmalıyız. Aşağıdaki defter yapısı bunu sağlıyor — ödeme sağlayıcısı değişse bile defter aynı kalır. > Avukat değilim. Yukarıdaki üç şartı ve sözleşme metnini bir ödeme hukuku avukatına > teyit ettir. Özellikle Şart 1, yanlış kurulursa idari para cezasından öteye giden bir > risk taşıyor. --- ## 2. Mevcut tablolar bu işi taşıyamaz `mp_customer_revenues` tablosunun şeması şöyle: ``` customer_id, order_id, sub_amount, fee, amount, current_balance, currency, type ``` Üç ciddi problem var. **Problem 1 — `current_balance` satır üzerinde tutuluyor.** Her kayıt, o andaki bakiyeyi kendi içinde saklıyor. Bu para işlerinde bilinen bir anti-pattern. İki eşzamanlı işlem aynı anda gelirse, ya da bir kayıt geriye dönük eklenir/silinirse, bakiye sessizce yanlışa gider ve **geri hesaplanamaz.** Kendi paranı yönetiyorsan tolere edilebilir; başkasının parasını tutuyorsan edilemez. **Problem 2 — Çift taraflı kayıt yok.** Tek kolonluk `amount` var. Para nereden geldi, nereye gitti sorusunun cevabı yok. Havuz hesabında ay sonunda banka ekstresiyle tutmayan 1.200 TL bulduğunda, hangi işlemden kaynaklandığını bulmanın yolu olmuyor. **Problem 3 — Eksik alanlar.** Stopaj matrahı ve tutarı yok, satıcı borç bakiyesi yok, komisyon oranı snapshot'ı yok, sözleşme versiyonu referansı yok, banka mutabakat izi yok. ### Çözüm: defter kaynak, mevcut tablo projeksiyon `mp_customer_revenues`'ı **silmiyoruz.** Satıcı panelindeki mevcut ekranlar bu tabloyu okuyor; silersek panelin yarısını yeniden yazmak gerekir. Bunun yerine: yeni defter **tek gerçek kaynak** olur, `mp_customer_revenues` defterden türetilen bir **projeksiyon** haline gelir. Defter değiştiğinde projeksiyon yeniden yazılır. Böylece mevcut panel çalışmaya devam eder, ama para gerçeği defterde durur. --- ## 3. Defter mimarisi Klasik çift taraflı muhasebe. Her işlem, borç ve alacak toplamı eşit olan bir **fiş** (entry) olarak yazılır. Fişler **asla güncellenmez veya silinmez** — düzeltme, ters kayıtla yapılır. ### Hesap planı | Kod | Hesap | Tip | Anlamı | |---|---|---|---| | `1000` | Havuz Banka Hesabı | Varlık | Fiziksel banka bakiyesi | | `1010` | Yolda Olan Tahsilat | Varlık | iyzico'da bekleyen, bankaya düşmemiş | | `2000` | Satıcı Alacağı `:store_id` | Yükümlülük | Satıcıya borcumuz (eksi ise satıcı bize borçlu) | | `2100` | Stopaj Borcu | Yükümlülük | Kesilen %1, vergi dairesine ödenecek | | `2200` | Müşteri İade Karşılığı | Yükümlülük | Onaylanmış ama ödenmemiş iadeler | | `4000` | Komisyon Geliri | Gelir | Pazaryeri komisyonu (KDV hariç) | | `4010` | Komisyon KDV'si | Yükümlülük | Tahsil edilen KDV | | `4100` | Kargo Geliri | Gelir | Satıcıya yansıtılan kargo | | `4200` | Ceza Geliri | Gelir | Sözleşmede tanımlı kesintiler | | `5000` | Ödeme Sağlayıcı Komisyonu | Gider | iyzico kesintisi | `2000` hesabı **satıcı başına** açılır. Eksi bakiye = satıcı borcu. Ayrı bir "borç hesabı" kurmuyoruz; işaret yeterli ve mutabakatı basitleştiriyor. ### Örnek 1 — Sipariş teslim edildi, hakediş hesaplanıyor 1.000 TL satış (KDV %20), komisyon %15, kargo 45 TL: ``` BORÇ ALACAK 1010 Yolda Olan Tahsilat 1.000,00 2000 Satıcı Alacağı :42 796,67 4000 Komisyon Geliri 125,00 4010 Komisyon KDV'si 25,00 4100 Kargo Geliri 45,00 2100 Stopaj Borcu 8,33 ───────── ───────── 1.000,00 1.000,00 ``` Stopajın 8,33 TL olduğuna dikkat: 833,33 TL (KDV hariç **brüt**) × %1. Komisyon ve kargo düşülmeden. Bu, Faz 2'de tespit ettiğimiz kural. ### Örnek 2 — Ödeme yapıldı (teslim + 3 iş günü) ``` BORÇ ALACAK 2000 Satıcı Alacağı :42 796,67 1000 Havuz Banka Hesabı 796,67 ``` ### Örnek 3 — İade geldi, ama para çoktan ödenmişti Faz 2'de bulduğumuz çelişkinin çözümü burada. 5 iş günü kuralı yüzünden parayı iade penceresi kapanmadan ödemek zorundayız. İade gelince: ``` BORÇ ALACAK 2000 Satıcı Alacağı :42 796,67 ← bakiye eksiye düşer 4000 Komisyon Geliri 125,00 ← komisyon geri verilir 4010 Komisyon KDV'si 25,00 2100 Stopaj Borcu 8,33 ← stopaj düzeltmesi 4100 Kargo Geliri 45,00 2200 Müşteri İade Karşılığı 1.000,00 ───────── ───────── 1.000,00 1.000,00 ``` Satıcının `2000` bakiyesi eksiye düştü. Sonraki hakedişte otomatik mahsup edilir. Satıcı ayrılırsa kalan borç `mg_store_balances.debt` üzerinde takip edilir. **Bu yüzden defter şart.** Tek kolonluk `current_balance` ile bu senaryo yönetilemez. --- ## 4. Havuz hesabı işletme kuralları Bunlar yazılımdan çok disiplin ama yazılımın zorlaması gereken şeyler. **Kural 1 — Havuz hesabı ayrı banka hesabı olmalı.** Şirketin işletme hesabıyla karışmamalı. Mevzuat bunu bu kelimelerle şart koşmuyor ama karıştığı anda mutabakat imkânsızlaşır ve bir denetimde savunulacak hikâye kalmaz. **Kural 2 — Satıcı parası işletme sermayesi olarak kullanılamaz.** Pazaryerlerinin battığı yer tam burası. Havuzda 3 milyon TL görüp reklam bütçesi yapmak, ertesi hafta hakedişi ödeyememek demek. Sistemde bunu zorlayacak gösterge: `1000` hesabının bakiyesi, her zaman `2000` hesaplarının toplamı + `2100` + `2200` toplamından **büyük veya eşit** olmalı. Altına düşerse kırmızı alarm. **Kural 3 — Günlük mutabakat.** Banka ekstresi her gün defterle karşılaştırılır. Eşleşmeyen kalem 24 saatten fazla açık kalmaz. **Kural 4 — Ters kayıt dışında düzeltme yok.** Hiçbir kullanıcı, hiçbir yetki seviyesi bir fişi güncelleyemez veya silemez. Yanlış kayıt, ters kayıtla kapatılıp yenisi yazılır. --- ## 5. Tablolar | Tablo | Görevi | |---|---| | `mg_ledger_accounts` | Hesap planı, satıcı bazlı alt hesaplar dahil | | `mg_ledger_entries` | Fiş başlığı, değiştirilemez | | `mg_ledger_lines` | Fiş satırları, borç/alacak | | `mg_store_balances` | Bakiye önbelleği — **defterden yeniden üretilebilir** | | `mg_order_settlements` | Sipariş bazlı hakediş detayı, komisyon oranı snapshot'ı | | `mg_payout_batches` | Günlük ödeme partisi | | `mg_payout_items` | Parti içindeki satıcı bazlı ödemeler | | `mg_bank_transactions` | Banka ekstresi ve eşleştirme durumu | | `mg_store_bank_accounts` | IBAN, hesap sahibi, doğrulama durumu | | `mg_contract_versions` | Sözleşme versiyonları (A4 gereği) | | `mg_store_contract_acceptances` | Satıcı hangi versiyonu ne zaman onayladı | `mg_store_balances` bir önbellek — bozulursa defterden sıfırdan üretilir. Kritik fark bu: `mp_customer_revenues.current_balance` bozulduğunda geri dönüş yoktu. Migration dosyası: `2026_07_24_000001_create_magostore_ledger_tables.php` --- ## 6. iyzico eklentisi: değişiklik gerekmiyor `fob-iyzipay` eklentisini inceledim. İçinde iyzico'nun **resmi PHP SDK'sı tam olarak geliyor** — `SubMerchant`, `CrossBookingToSubMerchant`, `PayoutCompletedTransactionList`, `InstallmentInfo` modelleri dahil. Ama eklentinin kendi kodu bunların hiçbirini kullanmıyor; yalnızca tek üye işyeri (standart) akışını çalıştırıyor. **Havuz modeli için bu tam olarak istediğimiz şey.** Alt üye işyeri seçseydik eklentiyi ciddi şekilde genişletmek gerekecekti; havuz modelinde standart akış zaten doğru: iyzico tahsil eder, tek hesaba (senin havuzuna) aktarır, dağıtımı sen yaparsın. Eklentiye eklenecek tek şey **taksit tablosu** (B3f): SDK'da `InstallmentInfo` hazır, sadece checkout ekranına bağlanması gerekiyor. Faz 3f'te yapılacak, mimariyi etkilemiyor. --- ## 7. Sıradaki iş 1. Migration'ı çalıştır, hesap planını seed et 2. `OrderDelivered` olayına bağlı hakediş fişi üreticisi (Örnek 1) 3. Günlük ödeme işi + banka dosyası üreticisi (Örnek 2) 4. İade fişi üreticisi + mahsup mantığı (Örnek 3) 5. `mp_customer_revenues` projeksiyon yazıcısı (mevcut panel çalışsın) 6. Mutabakat ekranı + Kural 2 alarmı 7. GMV 12 ay penceresi göstergesi (50 milyon TL eşiği) Bunlardan 2, 3 ve 4 sıralı bağımlı. 5, 2 bittikten sonra paralel gidebilir.