Withdrawal Experience
Withdrawal flow'un neden API-only olduğunu ve kullanıcı deneyiminin partner sitede kaldığını açıklar.
Withdrawal flow, deposit flow'dan farklıdır. Bugünkü External API contract'ında
POST /external/withdrawals kullanıcıya açılacak bir hosted withdrawal URL'i
döndürmez.
Bu bilinçli bir ayrımdır:
- Withdrawal request'i partner site backend'i açar.
- Kullanıcıdan IBAN ve holder name partner site üzerinde alınır.
- Pientegra payout request'ini işler.
- Sonuç partner site backend'ine webhook olarak gelir.
Flow
1. Kullanıcı partner sitede withdrawal formunu doldurur.
2. Partner backend fraud, balance ve business rule kontrollerini yapar.
3. Partner backend Pientegra'ya POST /external/withdrawals gönderir.
4. Pientegra withdrawalId ve referenceNo döner.
5. Pientegra payout'u işler.
6. Pientegra sonucu withdrawal.* webhook'u ile partner backend'e gönderir.
7. Partner site kullanıcı bakiyesini ve withdrawal state'ini günceller.Neden hosted withdrawal page yok?
Withdrawal tarafında source of truth genellikle partner sitenin kullanıcı hesabı, KYC/fraud kuralları ve balance ledger'ıdır. Bu nedenle kullanıcı deneyiminin partner site içinde kalması daha nettir.
Pientegra'nın rolü payout request'ini almak, işlemek ve sonucu signed webhook ile bildirmektir.
Partner UI önerisi
Partner site withdrawal ekranında şu state'leri gösterebilir:
| Partner UI state | Pientegra state/event |
|---|---|
| Talep alındı | POST /external/withdrawals başarılı response |
| İncelemede | withdrawal.created veya local pending state |
| Gönderildi | withdrawal.sent |
| Reddedildi | withdrawal.rejected |
| İade edildi | withdrawal.returned |
Balance model seçimi
Withdrawal için iki güvenli model vardır:
| Model | Açıklama |
|---|---|
| Pre-reserve | Kullanıcı request açınca balance reserve edilir. withdrawal.sent ile finalize, withdrawal.rejected ile release/refund yapılır. |
| Final debit | Balance sadece withdrawal.sent geldiğinde düşülür. |
Pre-reserve modeli gaming ve wallet sistemlerinde daha yaygındır, çünkü kullanıcı aynı bakiyeyle tekrar withdrawal açamaz. Ancak hangi modelin doğru olduğu partner ledger tasarımına bağlıdır.
İlerleyen sürümlerde public hosted withdrawal confirmation flow eklenebilir; o zaman ayrı bir integration model olarak bu sayfa güncellenir.