NetFinance API Entegrasyon Rehberi

Bu dokuman, bir partner sitenin NetFinance ile yatirim/cekim operasyonunu uca uca nasil devreye alacagini anlatir. Akis methods > deposit/withdrawal > callback modeliyle ilerler.

Base URL: /api/services/* Auth: X-Api-Key + X-Secret-Key Currency: TRY (v1) Iframe: /pay/{token} Embed: Cross-origin iframe destekli
Anasayfaya don

1) Entegrasyon Oncesi Hazirlik

  1. Panelden site kaydiniz acilir ve size API kimlik bilgileri atanir.
  2. Callback URL netlestirilir ve API key/secret teslimi tamamlanir.
  3. Ortamlar ayrilir: test ve canli ortam icin farkli key/secret kullanilir.
  4. Saha ve havuz eslesmeleri yapilir; aktif yontemler methods endpointinde gorunur.
  5. Superadmin panelindeki Odeme Yontemleri ekranindan fallback USDT/TRY kuru ve yatirim/cekim marjlari canli guncellenebilir.

2) Kimlik Dogrulama ve Ortak Basliklar

Tum korumali endpointlerde asagidaki header bilgileri gonderilmelidir.

X-Api-Key: nfk_your_site_key X-Secret-Key: your_site_secret Content-Type: application/json

Yanlis veya eksik kimlikte servis 401/403 donebilir. Islem akisini bozmamak icin retry ve log takibi yapin.

3) Aktif Yontemleri Cekme (Methods)

GET /api/services/methods
{ "status": "success", "deposit_methods": ["crypto", "havale", "papara"], "withdrawal_methods": ["crypto", "havale", "papara"] }

Partner frontend, kullaniciya sadece burada donen aktif yontemleri gostermelidir.

4) Deposit Akisi ve Iframe

  1. Partner backend, oyuncu yatirim isteginde deposit endpointine istek atar.
  2. Basarili cevapta tam URL olarak iframe link ve token doner.
  3. Partner frontend, donen linki kendi domaininde iframe icinde dogrudan acabilir.
  4. Oyuncu odemeyi tamamlayinca pay ekraninda onay adimini gecer.
  5. Final durum callback ile siteye asenkron iletilir.
POST /api/services/deposit { "payment_method_id": "havale", "amount": "1500.00", "user": "player_1001", "name": "Ali Veli", "user_id": "1001", "site_reference_number": "DEP-1001-20260727", "return_url": "https://site.com/wallet/result" }
{ "status": "success", "message": "Istek basariyla tamamlandi.", "iframe": { "link": "https://netfinance-domain/pay/{token}", "token": "...", "expires_at": "2026-07-28 12:00:00" } }

Not: return_url alaninda tam URL, schemesiz domain veya partner paneline ait goreli path kullanabilirsiniz. Iframe sayfasi cross-origin olarak gomulebilir; ayri domain zorunlulugu yoktur.

Iframe Gorunum Onizlemesi
/pay/token-ornegi

4.1) Kripto Yatirim Akisi (USDT > TRY)

Kullanici kripto yatirim secerse partner backend yine TRY tutari ile deposit endpointine istek atar. NetFinance, aktif USDT cuzdani ve korumali kur ile kullaniciya gonderecegi tam USDT miktarini hesaplar.

POST /api/services/deposit { "payment_method_id": "crypto", "amount": "4700.00", "user": "player_2001", "name": "Can Demo", "user_id": "2001", "site_reference_number": "DEP-CRYPTO-2001", "return_url": "https://site.com/wallet/result" }
{ "status": "success", "message": "Istek basariyla tamamlandi.", "iframe": { "link": "https://netfinance-domain/pay/{token}", "token": "...", "expires_at": "2026-07-28 12:00:00" }, "crypto_quote": { "coin": "USDT", "network": "TRC20", "wallet_address": "T...", "market_rate_try": "47.00000000", "effective_rate_try": "46.90000000", "quoted_crypto_amount": "100.21321962" } }
  1. Partner kullaniciya 4700 TRY yatirim olusturur.
  2. NetFinance piyasa kurunu okur ve kasayi koruyan efektif kur hesaplar.
  3. Iframe icinde aktif USDT adresi, ag bilgisi ve gonderilmesi gereken net USDT miktari gosterilir.
  4. Finans onayi sonrasinda partner kullanicisinin hesabina TRY olarak request amount yansitilir.

Ornek: piyasa kuru 47.00 ise korumali efektif kur 46.90 olabilir. Bu durumda kullanici 4700 TRY kredi almak icin yaklasik 100.21321962 USDT gonderir. Boylece alis-satis farki kasaya zarar yazmaz.

5) Withdrawal Akisi

POST /api/services/withdrawal { "payment_method_id": "havale", "amount": "1200.00", "user": "player_1001", "name": "Ali Veli", "user_id": "1001", "site_reference_number": "WDR-1001-20260727", "withdrawal_iban": "TR330006100519786457841326", "withdrawal_account_name": "Ali Veli" }
{ "status": "success", "message": "Istek basariyla tamamlandi.", "token": "...", "transaction_status": "pending", "approval_owner": "netfinance" }

Cekim talepleri once pending olarak kayit olur; operasyon onayi sonrasinda callback ile final durum doner.

Alternatif alanlar: - havale: withdrawal_iban + withdrawal_account_name veya withdrawal_info - crypto: withdrawal_crypto_address + withdrawal_crypto_network veya withdrawal_info - papara: withdrawal_info - hedef havuz secimi gerekiyorsa: target_iban_id veya target_crypto_id (yalnizca tek kanal)

5.1) Kripto Cekim Akisi (TRY > USDT)

Kullanici kripto cekmek istediginde partner backend tutari yine TRY olarak gonderir. NetFinance aktif USDT havuzunu kullanir, TRY tutarini korumali kur ile USDT'ye cevirir ve bu quote u response'ta dondurur.

POST /api/services/withdrawal { "payment_method_id": "crypto", "amount": "4700.00", "user": "player_2001", "name": "Can Demo", "user_id": "2001", "site_reference_number": "WDR-CRYPTO-2001", "withdrawal_crypto_address": "TLa2...", "withdrawal_crypto_network": "TRC20" }
{ "status": "success", "message": "Istek basariyla tamamlandi.", "token": "...", "transaction_status": "pending", "approval_owner": "netfinance", "crypto_quote": { "coin": "USDT", "network": "TRC20", "market_rate_try": "47.00000000", "effective_rate_try": "47.33100000", "quoted_crypto_amount": "99.30000000" } }
  1. Partner 4700 TRY cekim talebi olusturur.
  2. NetFinance aktif USDT havuzundan odeme yapacak quote u hesaplar.
  3. Finans onayi sonrasinda kullanicinin belirttigi kripto adrese quoted USDT miktari gonderilir.
  4. Partner tarafinda islem TRY cekim olarak kapanir, NetFinance ise arkada USDT odemeyi tamamlar.

Ornek: piyasa kuru 47.00 iken korumali efektif cekim kuru 47.331 olabilir. Bu durumda 4700 TRY cekim talebi icin yaklasik 99.30000000 USDT odenir. Boylece spread kasayi korur.

6) Callback Sozlesmesi

NetFinance, islem final duruma geldiginde panelde site icin tanimli callback_url adresine sunucudan sunucuya POST atar. Partner callback endpointi idempotent tasarlanmalidir.

POST https://partner-site.com/callback { "site_reference_number": "DEP-1001-20260727", "token": "optional-token", "status": "approved", "resolution_note": "manual kontrol tamam", "crypto_quote": { "coin": "USDT", "network": "TRC20", "quoted_crypto_amount": "99.30000000", "market_rate_try": "47.00000000", "effective_rate_try": "47.33100000" } }
approved: Islem basarili rejected: Islem reddedildi pending: ara durum, final degil

Not: crypto_quote alani yalnizca kripto akisi olan islemlerde gonderilir. /api/services/callback endpointi partnerin NetFinance'a geri bildirim gecmesi icindir; partnere giden callback adresi site bazli kaydedilen callback_url alanidir.

7) Hata Yonetimi ve En Iyi Pratikler

  1. site_reference_number degerini her islem icin benzersiz uretin (idempotency icin kritik).
  2. 422 yanitlarini kullaniciya acik mesaja cevirin; ham hata metnini loglayin.
  3. Callback endpointinde 2xx disi hatalarda kontrollu retry uygulayin.
  4. Token/secret bilgilerini sadece sunucu tarafinda saklayin, frontend'e cikarmayin.