# Ödeme, Döviz ve Checkout Altyapısı

## Amaç

OnlyCoin ödeme modülü VIP ve presale ödeme emirlerini tek domain modeli altında toplar. Kullanıcı ödeme yöntemini seçer; sunucu fiyatı, kur bilgisini, sağlayıcı limitini ve sipariş yetkisini yeniden hesaplar.

## Desteklenen ödeme sınıfları

### Kart / hosted checkout

- PayTR Link API adapter'ı
- iyzico hosted profil
- ParamPOS generic hosted profil
- Sipay generic hosted profil
- Paynet generic hosted profil
- Binance Pay generic hosted profil — varsayılan kapalı

Generic hosted profilde admin aşağıdaki URL şablonunu sağlayabilir:

```text
https://provider.example/pay?order={orderId}&reference={reference}&amount={amount}&currency={currency}&callback={callbackUrl}&session={sessionId}
```

Bu profil, gerçek sağlayıcının resmi API adapter'ının yerine geçmez. Sağlayıcının kendi imza, token ve status API sözleşmesi farklıysa özel adapter geliştirilmelidir.

### Banka / SWIFT

- TRY havale/EFT
- USD, EUR, GBP veya eklenen başka döviz hesapları
- Hesap sahibi
- IBAN
- SWIFT/BIC
- Hesap numarası ve şube
- Minimum/maksimum tutar
- Kullanıcıya gösterilen sipariş referansı
- Yönetici inceleme akışı

### Kripto fonlama

Kripto transferi ayrı bölgesel kontrol katmanına sahiptir. Ayrıntı: `CRYPTO_FUNDING_AND_TURKEY.md`.

## Para birimi modeli

`fiat_currencies` tablosu:

- ISO kodu
- ad
- sembol
- decimals
- active/base durumu
- sıralama

`fx_rates` tablosu, **1 birim dövizin TRY karşılığını 1e8 ölçeğinde** saklar.

Örnek:

```text
USD/TRY = 47.25000000
rate_to_try_e8 = 4,725,000,000
```

Tüm ödeme tutarları para biriminin en küçük biriminde saklanır:

```text
TRY 99.90  → 9990
USD 19.90  → 1990
USDT 19.90 → 19,900,000 mikro USDT
```

## TCMB kur senkronizasyonu

Admin → Döviz & Kur → “TCMB Kurlarını Güncelle” işlemi:

1. TCMB `today.xml` verisini HTTPS üzerinden alır.
2. `Unit` değerini dikkate alır.
3. Öncelikle Forex Selling, yoksa Forex Buying değerini kullanır.
4. Sistemde tanımlı para birimlerini günceller.
5. Kaynağı `tcmb` olarak işaretler ve güncellenme zamanını kaydeder.
6. Audit kaydı oluşturur.

TCMB kurunun bilgilendirici/gösterge niteliği ile merchant settlement kuru aynı olmak zorunda değildir. Sağlayıcı mutabakatı ayrıca kontrol edilmelidir.

## VIP fiyatları

`vip_plan_prices` ile her VIP seviyesi ve para birimi için sabit fiyat tanımlanır.

Örnek:

```text
VIP 1: 470 TRY / 9.90 USD / 9 EUR / 9.90 USDT
VIP 2: 950 TRY / 19.90 USD / 18 EUR / 19.90 USDT
```

Sabit fiyat yoksa sistem USDT temel fiyatını döviz kuru üzerinden hesaplar.

## Checkout durumları

Ödeme emri:

```text
created → submitted/verifying → paid
                         └──→ rejected/failed
```

Checkout oturumu:

```text
created → ready → paid
              └→ failed/expired
```

## Idempotency

- Her checkout isteği `Idempotency-Key` gerektirir.
- Aynı anahtar ve aynı istek önceki sonucu döndürür.
- Aynı anahtar farklı VIP seviyesi, presale tutarı, sağlayıcı veya para biriminde kullanılırsa `IDEMPOTENCY_KEY_CONFLICT` döner.
- Webhook provider event ID benzersizdir.
- Aynı callback ikinci kez entitlement veya token tahsisi oluşturmaz.

## PayTR adapter'ı

Yerel adapter:

- Merchant ID, Merchant Key ve Merchant Salt
- Link API token üretimi
- TL/TRY, USD, EUR, GBP ve RUB kodlaması
- QR talebi
- Callback ID
- Callback hash doğrulama
- Sipariş tutarı kontrolü
- Başarılı callback'te ödeme uygulama

Callback:

```text
POST /api/webhooks/paytr
```

PayTR callback'in başarılı kabul edilmesi için sunucu düz `OK` döndürür.

## Hosted provider callback'i

```text
POST /api/webhooks/generic/:providerId
X-OnlyCoin-Signature: HMAC-SHA256(raw-body)
```

Desteklenen başarı durumları:

```text
paid, success, completed
```

Desteklenen başarısız durumları:

```text
failed, rejected, cancelled
```

## Secret yönetimi

Provider secret'ları:

- `AUTH_SECRET` üzerinden türetilen AES-256-GCM anahtarıyla şifrelenir.
- Admin API'de maskelenir.
- Boş gönderildiğinde mevcut secret korunur.
- `__CLEAR__` ile kontrollü temizlenebilir.
- Audit log'a açık değer yazılmaz.

Üretimde `AUTH_SECRET` değiştirilmeden önce provider secret yeniden şifreleme planı uygulanmalıdır.

## Güvenli yayın kontrolü

- Sağlayıcı merchant sözleşmesi tamamlandı mı?
- Test ve canlı anahtarlar ayrıldı mı?
- Callback public HTTPS mi?
- Callback imzası doğrulanıyor mu?
- Minimum/maksimum tutar merchant paneliyle uyumlu mu?
- Etkin para birimleri merchant hesabında gerçekten açık mı?
- Başarı/iptal/iade webhook'ları test edildi mi?
- Mutabakat raporu var mı?
- Chargeback/refund entitlement geri alma akışı test edildi mi?
- Secret manager ve rotasyon hazır mı?
