Genel Bakış#
FinansZ POS API, ödeme terminal yönetimi, dijital POS ödeme akışları ve taksit bazlı terminal yönlendirme işlemlerini kapsar.Bu servis, tenant bazlı ödeme altyapısını yönetir ve aşağıdaki temel alanlardan oluşur:2D (non-secure) ödeme işlemleri
3D ödeme başlatma işlemleri
Taksit bazlı terminal yönlendirme
Sağlayıcı ve terminal yetenek yönetimi
Temel Kapsam#
POS API aşağıdaki iş ihtiyaçlarını karşılar:Terminal Yönetimi#
Sanal POS terminallerinin oluşturulması, güncellenmesi, aktif/pasif hale getirilmesi ve sağlayıcı bazlı ayarlarının yönetilmesini sağlar.Ödeme İşlemleri#
2D ve 3D ödeme akışlarını başlatır, ödeme kayıtlarını oluşturur ve seçilen terminal üzerinden provider tarafına işlemi iletir.BIN ve Taksit Sorgulama#
Kartın ilk 6 hanesine göre kart bilgisi alınmasını ve uygun terminaller üzerinden taksit seçeneklerinin sorgulanmasını sağlar.Taksit Bazlı Terminal Yönlendirme#
Tenant bazında tanımlanan kurallara göre, taksit sayısına bağlı olarak uygun terminalin otomatik seçilmesini sağlar.Önemli Kurallar#
Swagger/OpenAPI bu servis için teknik source-of-truth kaynağıdır.
Controller üzerinde route olarak expose edilmeyen backend method'ları dokümantasyonda görünmez.
Otomatik terminal seçimi, ödeme anında backend tarafında resolver ile yapılır.
useAutomaticRouting = true gönderildiğinde son terminal seçimini backend yapar.
Manuel terminal seçildiğinde mevcut akış doğrudan seçilen terminal üzerinden ilerler.
Sağlayıcı Davranışları#
Rubikpara#
Rubikpara terminali BIN sorgulama ve taksit sorgulama desteği sağlayabilir.otomatik routing içinde uygun aday terminal
Nurol#
Nurol tarafında bazı yetenekler sınırlıdır.BIN inquiry desteği yoktur
taksit inquiry desteği yoktur
tek çekim komisyonu terminal ayarından manuel tanımlanır
çok taksitli akışlarda aday terminal olarak değerlendirilmemelidir
Authentication#
Korumalı endpoint'lerde Bearer token kullanılır.Authorization: Bearer {{access_token}}
Accept-Language: {{culture}}
Ana Endpoint Grupları#
Terminals#
Terminal oluşturma, güncelleme, listeleme ve terminal ayarlarını yönetir.terminal sağlayıcı ayarlarını güncelleme
manuel banka etiketi tanımlama
Nurol için tek çekim komisyon oranı tanımlama
Payments#
2D (non-secure) ödeme oluşturma işlemlerini yönetir.Bu grup, ödeme oluşturma ve ödeme kaydının provider ile senkron yürütülmesini kapsar.ThreeD#
3D ödeme başlatma akışlarını yönetir.Bu grup, kullanıcıyı 3D doğrulama akışına sokan başlangıç kayıtlarını oluşturur.Installments#
Kart ve tutar bilgisine göre taksit seçeneklerini döner.Inquiry için kullanılan terminal, otomatik modda gerçek ödeme terminalinden farklı olabilir.
Provider uygun veri döndürmezse sonuç tek çekim ile sınırlı kalabilir.
Bin Inquiry#
Kartın ilk 6 hanesine göre kart tipi / banka bilgisi üretir.Installment Routing#
Taksit sayısına göre hangi terminalin kullanılacağını belirleyen tenant bazlı yönlendirme profilini yönetir.Desteklenen yönlendirme tipleri:varsayılan terminal fallback
Provider Settings#
Sağlayıcı bazlı capability ve varsayılan destek bilgilerini yönetir.Kritik İş Akışları#
1. Terminal Oluşturma#
İlk olarak uygun provider seçilir, ardından terminal oluşturulur.Terminal tanımlarken aşağıdaki bilgiler kritik olabilir:installment inquiry desteği
Nurol için tek çekim komisyon oranı
2. Taksit Bazlı Terminal Yönlendirme Tanımlama#
Tenant tarafında varsayılan terminal ve taksit bazlı kurallar kaydedilir.1 taksit -> sabit terminal
2 taksit -> kendi kartının bankası
3 taksit -> sabit Rubikpara terminali
4+ taksit -> en düşük komisyon
3. Digital POS ile Otomatik Ödeme#
Frontend tarafında kullanıcı terminal olarak Otomatik seçebilir.1.
UI gerekli inquiry işlemlerini uygun terminal üzerinden yapar
2.
ödeme submit edildiğinde useAutomaticRouting = true gönderilir
3.
backend resolver gerçek terminali belirler
4.
ödeme seçilen gerçek terminal üzerinden işlenir
4. Kart Bankasına Göre Yönlendirme#
Routing tipi Kendi kartının bankası seçildiğinde:1.
BIN sorgusu ile kart bankası belirlenir
2.
ManualBankLabel ile eşleşen terminal aranır
3.
eşleşme bulunamazsa varsayılan terminal kullanılır
Bilinen Kısıtlar#
Inquiry için kullanılan terminal ile gerçek ödeme terminali aynı olmak zorunda değildir.
Provider capability ile routing kuralı çelişirse fallback veya hata oluşabilir.
Nurol taksit inquiry desteklemediği için çok taksitli akışlarda uygun aday olmayabilir.
Contract'ta tanımlı olup controller'da expose edilmeyen method'lar Swagger ve Apidog tarafında görünmez.
Hata Yönetimi#
Karşılaşılabilecek hata türleri:uygun terminal bulunamaması
terminal capability uyumsuzluğu
provider kaynaklı işlem hataları
Test Önerileri#
Aşağıdaki akışlar özellikle doğrulanmalıdır:1.
Terminal oluşturma ve güncelleme
2.
Manuel banka etiketi kaydetme
3.
Nurol tek çekim komisyon oranı doğrulama
4.
Installment routing get/save
8.
Tek çekim ve çoklu taksit senaryoları
9.
Kart bankasına göre yönlendirme
10.
Varsayılan terminal fallback davranışı
Operasyonel Kural#
Yeni bir POS endpoint'i eklendiğinde şu sıra izlenmelidir:1.
Controller route'u kontrol edilir
2.
Swagger'da göründüğü doğrulanır
3.
Gerekirse proxy yeniden üretilir
5.
Gerekliyse ilgili rehber dokümanı güncellenir
Modified at 2026-03-05 07:06:53
