Cüzdan

Cüzdan, kendi markanız altında program-içi hesaplar işletmenizi sağlar: müşterileriniz bakiye yükler, birbirine gönderir, sizden alışveriş yapar, QR ile öder, puan ve cashback kazanır. Bakiye tek bir defter (double-entry ledger) üzerinde tutulur; her hareket bir operasyon kaydı ve denetim izi üretir.

Tüm tutarlar minor-unit (kuruş) tam sayıdır ve string olarak taşınır: "amount": "10050" = ₺100,50. Cüzdan API'sinde hiçbir yerde ondalıklı ya da float tutar yoktur.

Üç yüzey

Aynı iş yeteneği üç ayrı yüzeyde, farklı yetki genişliğiyle açılır. Uçlar ayrı controller'lardır; tek bir uç üç farklı kimlikle paylaşılmaz.

Yüzey	Kim çağırır	Path	Kimlik doğrulama	Uç
Dış API (s2s)	Sizin backend'iniz	`/api/v1/wallet/*`	Her istek Ed25519 ile imzalanır — imzanın kendisi kimliktir, Bearer'a çevrilmez	60
Portal / SDK	Son kullanıcının mobil/web uygulaması	`/api/portal/v1/wallet/*`	Publishable key → OTP → müşteri oturumu (JWT)	87
Merchant panel	Sizin operasyon ekibiniz	`/api/panel/v1/wallet/*`	Panel oturumu (JWT) + RBAC + dört-göz	186

Örnek: "işlem listesi" üç yüzeyde de vardır ama s2s tenant'ın tüm işlemlerini, panel tüm işlemleri (PII maskeli), portal yalnızca oturum sahibinin kendi işlemlerini döndürür.

⚠️

Yüzeyler birbirinin yerine geçmez: panelin 139 ucunun s2s API'de karşılığı yoktur, yani kendi merchant panelinizi imza anahtarıyla yazamazsınız. Ölçülmüş karşılaştırma: yüzey karşılaştırma matrisi.

🔑Kimlik Doğrulama→⚡Hızlı Başlangıç→🧩Temel Kavramlar→🗺️Yol Haritası→

Ne yapabilirsiniz

Yetenek	Açıklama	Durum
Program & marka	Kendi cüzdan programınız: para birimleri, marka, ücret ve limit politikası	✅
Son kullanıcı & hesap	Bireysel (`PERSONAL`) ve işletme (`BUSINESS`) kullanıcılar, çoklu para birimi hesapları	✅
Kart ile yükleme	Kartla bakiye yükleme — ödeme altyapısına delege edilir, 3D Secure dahil	✅
Temsilci ile yükleme	Bayi/temsilci nakit alır, float hesabından müşteriye kredi geçer	✅
Cüzdandan cüzdana transfer	Telefon veya cüzdan numarasıyla gönderim, OTP'li onay	✅
Cüzdanla ödeme	Müşteri → işletme ödemesi, komisyon ve kasiyer referansı	✅
QR	QR üretme, okuma, QR ile tahsilat ve ödeme	✅ (kapalı devre)
Sadakat	Cashback kampanyaları, puan, seviye (tier) ve rozet	✅
Limit & ücret	KYC seviyesine göre limit sayaçları, ücret şeması ve quote	✅
Cüzdana iade	Kart ödemesinin iadesini karta değil cüzdana kredi olarak yatırma	✅
Havale/EFT ile yükleme	Kullanıcıya özel yatırma talimatı, eşleşen para otomatik kredilenir	🚧
Bankaya çekim & IBAN transfer	Kullanıcının kendi IBAN'ına çekim, üçüncü şahsa IBAN transferi	🚧
Toplu ödeme	CSV/liste ile çoklu ödeme, maker-checker onayı	🚧
Fatura & fatura ödeme	Cüzdan içi fatura kesme; kurum faturası sorgulama ve ödeme	🚧
ATM / QR ile nakit çekim	Kart olmadan nakit çekim kodu	🚧
Kart ihracı	Cüzdana bağlı sanal/fiziksel kart	🚧

🚧 işaretli yetenekler için API sözleşmesi hazır ve kararlıdır; üretimde çalışması bağlı bir sağlayıcı (banka entegrasyonu, fatura kurumu, ATM ağı, kart ihraççısı) gerektirir. Ayrıntı: Yol Haritası.

Operasyon yaşam döngüsü

Para hareket ettiren her çağrı bir operasyon üretir. Operasyon durumları — GET /wallet/operations/:id yanıtında ve webhook payload'larında birebir bu değerleri görürsünüz:

Mutlu yol ve başarısız sanılan iki bekleme durumu. Terminal durumlar (FAILED, REVERSED, EXPIRED) ve risk tutması (HELD) şemaya girmedi — hepsi aşağıdaki tabloda. Şemanın anlattığı tek şey şu: BANK_PROCESSING ve AWAITING_RECON yolun ortasıdır, sonu değil.

Durum	Anlamı
`INITIALIZED`	Operasyon açıldı, fon rezerve edildi, henüz onay bekliyor
`CHALLENGED`	OTP / step-up doğrulaması bekleniyor
`POSTING`	Defter kayıtları işleniyor
`COMPLETED`	Tamamlandı — bakiyeye yansıdı
`FAILED`	Nihai başarısızlık; rezerve fon serbest bırakıldı
`REVERSED`	Tamamlanmış operasyon ters kaydedildi (iade/geri alma)
`REVERSING`	Geri alma başladı, defter sonucu bekleniyor; sistem otomatik olarak sonuçlandırır
`BANK_PROCESSING`	Banka tarafında işleniyor
`AWAITING_RECON`	Sonuç belirsiz — sessizce `FAILED` yapılmak yerine mutabakata alındı
`HELD`	Risk kararı nedeniyle tutuldu; para bloke, kullanılamaz
`EXPIRED`	Onaylanmadan süresi doldu; rezervasyon çözüldü

⚠️

AWAITING_RECON, HELD ve REVERSING terminal değildir. Bu durumlardaki operasyonu başarısız sayıp yeniden denemeyin — aynı Idempotency-Key ile sorgulayın veya webhook'u bekleyin.

Para hareketi deseni: quote → execute → complete

Para çıkaran işlemlerin çoğu üç adımlıdır. Bu, kullanıcıya ücreti hesaptan düşülmeden önce göstermek ve onayı doğrulamak içindir:

/quote — ücret, vergi, limit uygunluğu ve varsa kullanılacak entegrasyon bilgisini döner. Para hareket etmez.
/… (execute) — operasyon açılır, fon rezerve edilir, gerekiyorsa OTP tetiklenir. integrityHash + nonce döner.
/…/:id/complete — quote'tan gelen integrityHash ve nonce ile onaylanır; OTP gerekiyorsa otpCode de eklenir.

integrityHash, adım 2'de gösterilen tutar/ücret ile adım 3'te işlenen tutarın aynı olduğunu garanti eder. Kullanıcıya gösterilen ile hesaptan çıkan farklıysa istek reddedilir.

Güvenlik modeli

Para hareketi = imza. s2s tarafında okumalar dahil her istek Ed25519 anahtarınızla imzalanır ve her çağrı, o anahtarda karşılık gelen cüzdan iznini gerektirir (Anahtar izinleri).
Idempotency zorunlu. Para hareket ettiren ve kayıt oluşturan çağrılarda Idempotency-Key header'ı zorunludur (tam liste). Aynı anahtar tekrar gönderilirse işlem tekrarlanmaz, ilk yanıt döner.
Dört-göz. Manuel müdahale, kampanya onayı ve toplu ödeme onayında isteği yapan ile onaylayan aynı kişi olamaz — bu kural rol kapısıyla değil, servis katmanında kimlik karşılaştırmasıyla zorlanır. Manuel müdahale kalıcı bir talep kaydıdır: talep eden ve onaylayan panel oturumlarından alınır, istek gövdesinden alınmaz.
Fail-closed. Bir kapı (limit, KYC, fraud, sağlayıcı) cevap veremiyorsa işlem reddedilir; "geçir gitsin" davranışı yoktur.

İlgili ürünler

Cüzdana İade — kart ödemesinin iadesini cüzdana kredi olarak yatırma
Payment Orchestrator — kartla yükleme bu altyapıya delege edilir
Fraud & Fraud AI — cüzdan çıkış işlemlerinde risk kararı
Identity — cihaz ve oturum zekâsı, portal oturumlarında

Temel Kavramlar