Para Çekme

Bu uçları kim çağırır?Dış API (s2s)

Taban yol: /api/v1/wallet
Kimlik: Ed25519 istek imzası — X-Key-Id, X-Date, X-Nonce, Digest (body varsa), X-Signature. Zaman penceresi ±5 dk, nonce tek kullanımlık, anahtarda IP allow-list olabilir.
Yetki: Anahtarınız cüzdan ürününü ve çağrının gerektirdiği cüzdan iznini taşımalıdır; izni olmayan çağrı 403 WALLET_INSUFFICIENT_SCOPE alır. Uç başına izinler: Anahtar izinleri.
Çapraz yüzey: Bu uçlar s2s yüzeyindedir. Son kullanıcı tarafı /api/portal/v1/wallet/me/withdrawals/*. Takılan çekime müdahale panele özeldir: POST withdrawals/:id/intervention-requests bir dört-göz talebi açar, başka bir yetkili onaylar (wallet:operation:intervene).

Kullanıcı bakiyesini iki yoldan dışarı çıkarabilir:

Yol	Nereye	Operasyon tipi
Banka çekimi	Kullanıcının kendi doğrulanmış IBAN'ı	`WITHDRAW_BANK`
Nakit çekim	ATM veya QR ile kartsız nakit	Nakit çıkış operasyonu

Üçüncü şahsın IBAN'ına gönderim çekim değil transferdir — bkz. Transfer → IBAN'a transfer. İkisi ayrı limit sayacı ve ayrı ücret şeması kullanır.

Banka çekimi

Yakında — banka entegrasyonu gerektirir

Aşağıdaki sözleşme tamamlanmıştır ve değişmeyecektir. Üretimde çalışması için programınıza bir banka entegrasyonu bağlanmalıdır; para dışarı bu entegrasyonla çıkar. Entegrasyon bağlı değilken bu uçlar istek kabul etmez. Durum: Yol Haritası.

Akış transferle aynı üç adımdır:

POST /api/v1/wallet/withdrawals/bank/quote
POST /api/v1/wallet/withdrawals/bank
POST /api/v1/wallet/withdrawals/bank/{operationId}/complete
GET  /api/v1/wallet/withdrawals/{operationId}

Alan	Tip	Zorunlu	Açıklama
`endUserId`	string	✅	İşlemi adına yaptığınız son kullanıcı; üç adımda da zorunlu
`sourceWalletAccountId`	string	✅	Çekimin yapılacağı hesap; `endUserId`'ye ait olmalıdır
`beneficiaryName`	string	✅	Hesap sahibinin adı
`iban`	string	✅	Kullanıcının kendi IBAN'ı
`bankCode`	string	—	Hangi banka entegrasyonunun kullanılacağını etkileyebilir
`amount`, `currency`	string	✅
`paymentPurpose`	string	—

Tamamlama gövdesi endUserId, operationId (yoldaki ile aynı kimlik), başlatma yanıtından gelen integrityHash ve nonce alanlarını, gerekiyorsa otpCode ya da trustedActionToken alanını taşır — tıpkı bir transferde olduğu gibi.

İzin: başlatma ve tamamlama adımları parayı platform dışına çıkardığı için anahtarınızda wallet:bank-payout:operate izni bulunmalıdır; bu izin açık devre (Growth) planında sunulur. Quote adımı ve GET /withdrawals/{operationId} için okuma izni yeterlidir. İzin yoksa çağrı 403 WALLET_INSUFFICIENT_SCOPE döner — bkz. Anahtar izinleri.

Durum akışı

AWAITING_RECON "başarısız" değildir; banka tarafındaki sonuç henüz netleşmemiştir. Bu durumdaki bir çekimi yeniden denemek çifte gönderim riski taşır — mutabakat sonucunu bekleyin.

Durum	Ne demek	Ne yapmalısınız
`BANK_PROCESSING`	Talimat bankada	Bekleyin; webhook gelecek
`AWAITING_RECON`	Sonuç belirsiz	Yeniden denemeyin — mutabakat sonucunu bekleyin
`COMPLETED`	Para bankaya geçti	`bankRef` dekontta görünür
`FAILED`	Banka reddetti	Rezervasyon çözüldü; sebep `failureCode`'da

⚠️

AWAITING_RECON terminal değildir. Bu durumdaki bir çekimi başarısız sayıp tekrar başlatmak çifte ödeme riskidir. Kullanıcıya "işleminiz kontrol ediliyor" gösterin.

IBAN sahipliği

Çekim, kullanıcının kendi hesabına yapılır. IBAN'ın gerçekten kullanıcıya ait olduğunun doğrulanması banka entegrasyonunun sunduğu yeteneğe bağlıdır; sağlayıcı bu kontrolü sunmuyorsa doğrulama sizin akışınızda yapılmalıdır (ör. kullanıcıdan hesap ekstresi/onayı).

Nakit çekim (ATM / QR)

Yakında — nakit çekim ağı bağlantısı gerektirir

Akışın tamamı (limit kontrolü, KYC kapısı, risk değerlendirmesi, kod üretimi, iptal ve mutabakat) hazırdır; eksik olan nakit çekim ağı bağlantısıdır. Ağ bağlı değilken kod üretimi reddedilir. Durum: Yol Haritası.

Kullanıcı uygulamada bir çekim kodu üretir, ATM'de ya da noktada bu kodla kartsız nakit alır.

Kod üretin

POST /api/panel/v1/wallet/cash-out

Alan	Tip	Zorunlu	Açıklama
`channel`	string	✅	`ATM` veya `QR`
`programId`	string	✅
`endUserId`	string	✅
`sourceWalletAccountId`	string	✅
`amount`, `currency`	string	✅
`trustedActionToken`	string	—	Step-up doğrulaması

Kod üretildiğinde tutar, işlemin ücreti ve vergisiyle birlikte bloke edilir — kullanıcı aynı parayı başka yerde harcayamaz. Ücret ve vergi nakit verildiğinde bu blokeden tahsil edilir.

Kullanıcı nakdi alır

Kullanıcı üretim yanıtındaki gizli kodu (plaintext) ATM'ye ya da noktaya girer. Ağ, dağıtımı onaylarken bu kodu da iletir; kod sunucuda doğrulanır ve yalnızca eşleşirse para verilir. Dağıtım teyidi işlendiğinde operasyon tamamlanır.

Kod eşleşmezse dağıtım reddedilir (WALLET_CASHOUT_CODE_INVALID) ve kodun deneme hakkından biri düşer.
Kod başına 5 hatalı deneme hakkı vardır. Hak bittiğinde kod kilitlenir (WALLET_CASHOUT_CODE_LOCKED) ve bloke tutarın tamamı (ücret ve vergi dahil) kullanıcıya iade edilir; kod doğru girilse bile artık kullanılamaz, yeni bir kod üretilmelidir.
Süresi dolmuş ya da tutarı henüz bloke edilmemiş bir kod dağıtılmaz.

Kullanılmazsa

Kod süresi dolduğunda blokaj çözülür; bloke edilen tutarın tamamı (ücret ve vergi dahil) kullanıcıya geri açılır. Kullanıcı isterse kodu erkenden iptal edebilir.

Risk kararı ve `HELD`

Nakit çıkış, geri alınması en zor para hareketidir; bu yüzden risk değerlendirmesinden geçer.

Risk kararı	Sonuç
Onay	Kod üretilir, para bloke
İnceleme (`review`)	Operasyon `HELD` olur — para bloke kalır ama ATM'de kullanılamaz
Ret	Kod üretilmez, blokaj yok

HELD operasyonu operasyon ekibiniz panelden çözer: onaylarsa kod kullanılabilir hâle gelir, reddederse para kullanıcıya iade edilir. Süre dolarsa otomatik iade edilir.

⚠️

HELD durumundaki bir operasyonu başarısız saymayın. Kullanıcıya "işleminiz inceleniyor" deyin; "başarısız" derseniz kullanıcı yeniden dener ve ikinci bir blokaj oluşur.

Limit ve KYC kapısı

Nakit çekimin kendi limit sayacı ve KYC seviye eşiği vardır. Programınızda nakit çekim için bir KYC eşiği tanımlanmamışsa kapı devreye girmez; eşik koymadan nakit çekimi açmak, seviye kontrolü olmadan nakit çıkışına izin vermek demektir.

Webhook'lar

Olay	Ne zaman
`wallet.withdrawal.processing`	Talimat bankada işleniyor
`wallet.withdrawal.completed`	Çekim tamamlandı
`wallet.withdrawal.failed`	Çekim başarısız, rezervasyon çözüldü
`wallet.withdrawal.awaiting_recon`	Sonuç belirsiz, mutabakata alındı
`wallet.withdrawal.reversed`	Tamamlanmış çekim ters kaydedildi

Yaygın hatalar

Durum	Sebep	Çözüm
Çekim `AWAITING_RECON`'da bekliyor	Banka tarafındaki sonuç netleşmedi	Beklemek doğru davranış; yeniden denemeyin
Bakiye görünüyor ama çekilemiyor	Bakiyenin bir kısmı başka operasyonda bloke	`GET /wallet/operations` ile açık operasyonlara bakın
Nakit kodu üretilmiyor	KYC seviyesi yetersiz veya limit dolu	KYC Seviyeleri · Limitler
Nakit kodu kilitlendi (`WALLET_CASHOUT_CODE_LOCKED`)	Kod 5 kez hatalı girildi; tutar iade edildi	Kullanıcıdan yeni bir kod üretmesini isteyin

Transfer Cüzdanla Ödeme