Çapraz sınır ödeme işi, dışarıdan bakınca “bir API bağla, bitsin” gibi duruyor. Gerçek öyle değil. Banka rayları, cüzdanlar, yerel para birimleri. Ülke bazlı kısıtlar aynı masaya oturunca ortalık ciddi anlamda karışıyor. Geçen sene, 2025 Mart’ta İstanbul’da bir SaaS ekibinin ödeme akışını incelerken tam da bunu gördüm: ABD’deki contractor’a USD gönderiyorsun, Kenya’daki ekip mobile money istiyor, Nijerya’daki serbest çalışan ise banka hesabı kullanmıyor bile. Yani tek tek entegrasyon yapmak kısa vadede idare eder ama büyüyünce —. Siz ne dersiniz? Kaçınılmaz olarak büyüyorsunuz — iş koca bir baş ağrısına dönüşüyor (inanın bana)
Bunu yaşayan biri olarak söyleyeyim, Bu yazıda Afriex SDK ile kurulan bir freelancer payout platformunu kendi gözümden anlatacağım. Next.js tabanlı yapı var, Drizzle ORM ile veritabanı konuşuluyor, TiDB Cloud arka tarafta duruyor ve Better Auth kimlik doğrulamayı hallediyor. Güzel tarafı şu: mimariyi katmanlara ayırınca hem kod okunuyor hem de ödeme akışı çok daha kontrollü bir hal alıyor. Kötü tarafı? Tabi, ilk kurulumda env dosyasıyla biraz boğuşuyorsunuz. Normal, neredeyse her zaman böyle.
Neden böyle bir platforma ihtiyaç var?
Hani, Freelancer ödemeleri çoğu zaman “basit finansal işlem” diye küçümseniyor. Pratikte bayağı çetrefilli. Bir ülkede banka transferi hızlıdır, diğerinde değil; bir yerde mobil cüzdan standarttır, başka yerde IBAN bile tek başına yeterli olmaz. Üstelik kur farkı da işin içine girince maliyet tahmini büyük ölçüde şaşar gider.
Hmm, bunu nasıl anlatsamdı…
Benzer bir problemi 2024 Kasım’da Ankara merkezli küçük bir ajansla çalışırken bizzat gördüm. Ajansın üç kıtaya yayılan tasarımcı ağı vardı. Her ay sonunda muhasebe ekibi resmen Excel savaşına giriyordu — kim ne aldı, hangi kurdan, hangi tarihte, neden bu kadar sürdü… Açık konuşayım, teknik borç sadece kodda olmuyor; ödeme operasyonunda da koca bir borç yığını oluşabiliyor. Bunu fark ettiğinizde iş çoğunlukla çığ gibi büyümüş oluyor.
Afriex yaklaşımının cazibesi tam burada başlıyor: farklı rail’leri tek kapıdan yönetmeye çalışıyorsun. Böylece uygulama tarafında “hangi ülkeye hangi yöntemle gönderirim?” sorusu biraz daha sadeleşiyor. Ama kağıt üstünde süper görünen şeylerin pratikte test edilmesi lazım — ben buna hep dikkat ederim, kör bir şekilde inanmak işe yaramıyor bu işlerde.
Mimariyi düzgün kurmazsanız iş büyüdükçe dağılır
İlginç olan şu ki, Yazının en sevdiğim kısmı mimari meselesi oldu. Burada gerçekten sağlıklı düşünülmüş bir ayrım var (en azından benim deneyimim böyle). Browser → Hook → Service → API Route → Repository / DAL şeklinde ilerleyen yapı. İlk bakışta “ya bu kadar katman ne gerek” diyebilirsiniz —. Her parçanın ayrı görevi olması sistemi inanılmaz rahatlatıyor, bunu yaşayarak öğrendim.
Bir dakika — bununla bitmedi.
Hook katmanı React Query ile cache (yanlış duymadınız). Loading state işini çözüyor; service katmanı kendi API’nize istek atıyor; API route validasyon yapıp repository ile DAL arasında köprü oluyor; repository veriyi saklıyor; DAL ise yalnızca Afriex SDK’ya dokunuyor. Yani dış dünya ile iç veri dünyasını birbirine karıştırmıyorsunuz. Bu ayrım kulağa kuru teori gibi gelebilir, değil. Gerçek anlamda hayat kurtarıyor.
“Veritabanınız UI durumunun kaynağı olabilir ama payout işleminin gerçeği harici servis tarafındadır.” Bu ayrımı net tutmazsanız yarın sabah destek ekibi size fena halde kızar!
Bir de şu var: bu ayrım startup için de enterprise için de işe yarıyor ama farklı sebeplerle. Küçük ekipte debug kolaylaşıyor. Büyük ekipteyse sorumluluk sınırları netleşiyor, kim neye bakacak belli oluyor, ortalık karışmıyor (inanın bana). Benim deneyimimde en çok kazandıran şey bu oldu — özellikle de ödeme gibi hassas alanlarda, hata toleransının neredeyse sıfır olduğu yerlerde bu katmanlı yapı gerçekten fark yaratıyor.
| Katman | Görev | Neden önemli? |
|---|---|---|
| Hook | Kullanıcı etkileşimi ve cache | Ekran hızlı hissettirir |
| Service | Kendi API’nize istemci olur | Kod tekrarını azaltır |
| API Route | Doğrulama ve orkestrasyon | Sistemi kontrol altında tutar |
| Repository | DB okuma/yazma | Tutarlılık sağlar |
| DAL | Afriex SDK çağrıları | Dış entegrasyonu izole eder |
Kurulum kısmı neden önemli? Çünkü hata genelde orada çıkıyor
Böyle projelerde ilk günler hep aynı döngü yaşanır: repo klonlanır, bağımlılıklar yüklenir,.env dosyası doldurulur… sonra biri eksik kalır ve sistem kalkmaz. O an insanın morali düşer. Normal. Hani ne farkı var diyorsunuz, değil mi? Dağıtık sistemlerin cilvesi bu, alışmak lazım.
Peki neden?
Şöyle söyleyeyim, Sorunsuz başlangıç için Node.js v22+ gerekiyor denmişti ki bu gayet mantıklı — modern paketler yeni runtime’larda daha az naz yapıyor. TiDB Cloud bağlantısı kurulurken SSL detaylarını kaçırmak da klasik hatalardan biri olur, özellikle gateway URL’si yanlışsa. Bir kere 2023’te kendi yan projemde benzer bir MySQL uyumlu bulut DB’de tam da bunu yaşamıştım; üç saatlik sorun aslında tek karakterlik connection string yüzünden çıkmıştı. Üç saat. Tek karakter. Evet.
git clone https://github.com/codewithveek/afriex-payout-platform.git
cd afriex-payout-platform
pnpm install
cp.env.example.env.local
pnpm run db:migrate
pnpm dev
Açık konuşayım,.env içinde AFRIEX_API_KEY, AFRIEX_ENVIRONMENT ve webhook public key gibi değerler var. Bunların her biri ayrı ayrı önemli çünkü sandbox ortamında yaptığınız testlerle canlı ortam davranışı birebir aynı olmayabilir — bu da beklediğinizden çok daha az güzel sürprizlere kapı aralıyor. Dikkatli olun.
Peki nerede dikkat etmek lazım?
- Payout öncesi alıcı doğrulamasını atlamayın.
- Döviz kuru çekimini kullanıcıya göstermeden önce cache stratejisi belirleyin.
- Webhook imzasını büyük ihtimalle doğrulayın.
- Email bildirimlerini ana akıştan ayırın ki sistem tıkanmasın.
- Migrasyonları prod öncesi iki kez test edin… hatta mümkünse üç kez. (bu kritik)
Afriex SDK entegrasyonu nasıl düşünülmeli?
Eh, interface veya service seviyesinde entegrasyon yapmak yerine DAL katmanına koymanın sebebi basit: harici API değişirse uygulamanın geri kalanı bundan minimum etkilenir. Maalesef bu her zaman hatırlanmıyor.
Eh, Ödeme platformlarında en sinir bozucu şeylerden biri şudur — bugün çalışan endpoint yarın ufak bir parametre farkıyla kırılır. Aynısını geçen ay editör masasında test ettiğim başka bir finans projesinde de gördüm; ekip doğrudan UI’dan dış servisi çağırıyordu ve hata ayıklamak gerçekten kabusa dönmüştü, ne loglar düzgün ne de hata mesajları anlamlıydı. HTML Entity Araması: Üç Formu Tek Ekranda Yakal… yazımızda bu konuya da değinmiştik.
Ama burada istek önce sizin API route’unuza geliyor, sonra repository veriyi kontrol ediyor, en son DAL Afriex’e gidiyor. Bu zincir sayesinde hem loglama kolaylaşıyor hem de retry mantığı eklemek çok daha temiz bir hal alıyor. İşin özü şu:
- Afriex üzerinden müşteri oluşturmak,
- bank account ya da mobile money wallet bağlamak,
- kur bilgisini çekmek,
- ve payout tetiklemek
— hepsi aynı omurganın parçaları gibi çalışıyor. Bu düzen iyi. Kusursuz değil ama iyi.
Mesela webhook gecikirse kullanıcı arayüzünde “beklemede” durumu uzayabiliyor. İşte tam burada status polling ya da event reconciliation devreye girebilir. Gel gelelim çoğu küçük ekip bunları sonradan düşünüyor… sonra gece yarısı alarm çalıyor. Kaçınılmaz gibi hissettiriyor ama değil, önceden planlanabilir.
Kullanıcı deneyimi kadar operasyonel detaylar da kritik
Freelancer panelinde görünmeyen kahraman genelde e-postadır. Payout başlatıldı mesajı gelir, tamamlandı bildirimi gelir, hata varsa destek ekibine düşer. Kulağa basit geliyor. Saha tarafında ciddi fark yaratıyor ama (ben de ilk duyduğumda şaşırmıştım) Crimson Desert’te Intel Desteği: Arc Sahneye Çıkıyor yazımızda bu konuya da değinmiştik. Daha fazla bilgi için HTTP Durum Kodları: 36 Kodu Tek Ekranda Topladım yazımıza bakabilirsiniz.
Şahsen, Resend entegrasyonu bu yüzden boş süs değil. Geçen yıl Eylül (belki yanılıyorum ama) ayında Londra’daki uzaktan çalışan küçük bir ürün ekibinde benzer bir email akışı kurmuştuk; ödeme sonrası manuel Slack mesajlarının %60’ını kesmişti. Küçük rakam gibi duruyor ama hafta sonunda insanlara nefes aldırıyor — ve nefes alabilen ekip daha iyi iş çıkarıyor, bu kadar basit.
Bir de UX tarafındaki bekleme hissini hafife almayın. Kullanıcı “gönderildi mi gitmedi mi?” diye ekran yeniliyorsa problem vardır (inanın bana). React Query’nin loading-state avantajı burada işe yarıyor: veriyi çekersiniz, cache’i korursunuz, sonra invalidation ile ekranı güncellersiniz. Basit görünür, fena değildir gerçekten.
Bir şey dikkatimi çekti: Startup senaryosunda en büyük avantaj hız: az kişiyle çalışırsınız, iş bölümü nettir, entegrasyonu çabuk çıkarırsınız. Enterprise tarafta ise audit trail, role-based access control, idempotency ve uyumluluk konuları öne çıkar. Yani aynı ürün iki farklı şirkette bambaşka ağırlık taşıyor — bunu göz ardı etmeyin, mimari kararlarınızı buna göre şekillendirin.
Zayıf noktalar ne? Her şey güllük gülistanlık değil tabii
Açık konuşayım: bu tip sistemlerde ilk hayal kırıklığı genelde gerçek zaman beklentisinden geliyor. Webhook’lar bazen geç düşer, bazen sıralama şaşar, bazen dış servis kısa süre tökezler… ve siz yine kullanıcıya açıklama yapmak zorunda kalırsınız. Kaçınılmaz mı? Hayır. Ama hazırlıksız yakalanırsanız acı verir.
Bir diğer konu da veri tutarlılığı. Veritabanınızda kayıt başarılı görünüp dış servis tarafında işlem askıda kalabiliyor. O yüzden “source of truth” kavramını net tanımlamak şart; aksi halde destek ekibi aynı işlem için iki farklı hikâye dinler durur, bu da müşteriyle ciddi güven sorununa yol açar.
Bence en sağlıklı yaklaşım şu:
- DB’de işlem niyetini saklayın.
- Dış servisteki gerçek sonucu ayrıca takip edin.
- Webhook + polling kombinasyonu kullanın.
- Hataları sınıflandırıp yeniden deneme stratejisi kurun. (bence en önemlisi)
Bir de şunu söyleyeyim: küresel payout işleri teknik olduğu kadar hukuki ve operasyoneldir de. KYC/AML süreçleri bazı pazarlarda sizi beklenmedik yere çekiyor (ben de ilk duyduğumda şaşırmıştım). Kod güzel olsa bile süreç zayıfsa sistem aksar. Bunu sonradan öğrenmek pahalıya patlıyor.
Sıkça Sorulan Sorular
Afriex SDK ile hangi tür ödemeler yapılabiliyor?
Banka hesabına transfer ve bazı bölgelerde mobile money cüzdanlarına ödeme yapılabiliyor.
Desteklenen yöntemler ülkeye göre değişebilir.
En doğru liste için resmi dokümantasyona bakmak gerekir.
This proje küçük ekipler için uygun mu?
Evet, özellikle birkaç ülkeye ödeme yapan freelance veya ajans ekipleri için uygun.
Ama başlangıçta webhook takibi ve hata yönetimini hafife almamak lazım.
İlk gün düzgün kurarsanız sonradan çok rahat edersiniz.
Neden direkt frontend’den Afriex çağrılmıyor?
Bunun güvenlik riski var.
API anahtarlarını tarafa gömmek istemezsiniz.
Ayrıca validasyon, logging. Business logic’i server-side tutmak çok daha temizdir.
Tidb yerine klasik MySQL kullanılabilir mi?
Evet kullanılabilir,
ama makaledeki yapı TiDB Cloud üzerinde kurulmuş.
Uyumluluk açısından yakın olsalar da üretimde performans ihtiyacınıza göre seçim yapmanız gerekir.
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
