← Ana Sayfaya Dön

🌉 H2H Bridge Partner API

Netfinance ile entegrasyonunuz ve hızlı ödeme işlemleri için tam API Dokümantasyonu

🎯 Giriş

H2H (Host-to-Host) Bridge Partner modu, bağlantılı sitelerinizin doğrudan Netfinance sistemine entegre olmasını sağlar. Bu mod sayesinde, partner siteleriniz kendi sistemlerinden doğrudan para yatırma ve çekme işlemleri gerçekleştirebilir.

ℹ️ Bilgi: Bridge Partner modu, API anahtarı ve gizli anahtar ile güvenli şekilde kimlik doğrulaması yapılan siteler için tasarlanmıştır.

🔐 Kimlik Doğrulama

Tüm H2H API isteklerinde aşağıdaki HTTP başlıklarını içermelisiniz:

Başlık Açıklama Örnek
X-Api-Key Sitenizin API anahtarı site_1234567890
X-Secret-Key Sitenizin gizli anahtarı secret_abcdefg...
⚠️ Uyarı: Gizli anahtarı asla istemci tarafında açıklamayın. Tüm API isteklerini güvenli sunucu ortamından yapın.

💰 Para Yatırma (Deposit)

Endpoint

POST /api/services/deposit

Açıklama

Bridge Partner modunda ödeme sayfası entegrasyonu yoktur. Müşteriniz parayı kendi ödeme arayüzünüz üzerinden gönderir; siz bu isteği yalnızca Netfinance'e yatırım bildirimi olarak atarsınız. İstek anında işlem "gönderildi" (oyuncu bildirimi yapıldı) olarak kaydedilir ve saha havuzunuzdan uygun bir IBAN/kripto cüzdanı otomatik seçilerek yanıt olarak size döner.

İstek Parametreleri

Parametre Türü Zorunlu Açıklama
amount Decimal ✓ Para yatırma tutarı (TRY)
player_username String Oyuncu kullanıcı adı (gönderilmezse otomatik üretilir)
player_name String Oyuncu adı soyadı
payment_method String iban veya crypto (gönderilmezse iban varsayılır)
site_reference_number String Kendi sisteminizdeki işlem referansı (gönderilmezse otomatik üretilir)
transaction_type String deposit (sabit, bilgi amaçlı; endpoint zaten yatırımı belirtir)

İstek Örneği

curl -X POST https://netfinance.example.com/api/services/deposit \ -H "X-Api-Key: site_1234567890" \ -H "X-Secret-Key: secret_abcdefg..." \ -H "Content-Type: application/json" \ -d '{ "amount": "500.00", "player_username": "oyuncu123", "player_name": "Ahmet Yilmaz", "payment_method": "iban", "transaction_type": "deposit" }'

Başarılı Yanıt (IBAN)

✓ HTTP 200

{ "status": "success", "message": "Istek basariyla tamamlandi.", "transaction_id": 12345, "account_title": "NETFINANS TICARET A.S.", "account_no": "TR920006200519000006773400", "bank_code": "Denizbank" }

Başarılı Yanıt (Crypto)

✓ HTTP 200

{ "status": "success", "message": "Istek basariyla tamamlandi.", "transaction_id": 12346, "crypto_quote": { "coin": "USDT", "network": "TRC20", "wallet_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKLxmGkn", "market_rate_try": "34.10", "effective_rate_try": "34.30", "quoted_crypto_amount": "14.58" } }

Yanıt Parametreleri

Parametre Açıklama
transaction_id Netfinance sistemindeki işlem ID'si
account_title Hesap sahibinin adı (IBAN için)
account_no Hedef IBAN numarası
bank_code Banka adı
crypto_quote Crypto yönteminde hedef cüzdan ve kur bilgisi
✓ Akış: Siz müşteriden parayı kendi ödeme sayfanızda toplarsınız, bu isteği yalnızca bildirim olarak atarsınız. İşlem Netfinance H2H panelinde "Gönderildi" durumunda belirir, ekibimiz dekontu kontrol edip onaylar/reddeder; sonuç callback_url'inize iletilir.

💸 Para Çekme (Withdrawal)

Endpoint

POST /api/services/withdrawal

Açıklama

Para çekme talebini oyuncunun hesabındaki çekim ekranından aldıktan sonra bu endpoint'e sunucunuzdan gönderin. Talep Netfinance H2H panelinde bekleyen işlem olarak oluşturulur; onay veya ret sonucu callback_url'inize bildirilir.

⚠️ Önemli: Çekim için kullanılan ödeme yönteminde çekim aktif olmalıdır. Yalnızca para yatırmayı destekleyen NTF gibi sağlayıcılar bu endpoint'te kullanılamaz. Çekim yöntemi adını GET /api/services/methods endpoint'inden kontrol edin.

İstek Parametreleri

Parametre Türü Zorunlu Açıklama
amount Decimal ✓ Çekim tutarı (TRY); yöntemin minimum ve maksimum limitleri uygulanır.
user String ✓ Oyuncunun kullanıcı adı. Bridge Partner için gönderilmezse referanstan üretilir.
name String ✓ Oyuncunun adı soyadı. Bunun yerine user_name da kullanılabilir.
user_id String ✓ Oyuncunun sitenizdeki benzersiz ID'si.
site_reference_number String ✓ Sitenizde benzersiz çekim referansı. Aynı referans ikinci kez kullanılamaz.
payment_method_id String ✓ havale, papara veya crypto. Bridge Partner için payment_method alias'ı da kabul edilir.
withdrawal_iban String Havale için ✓ Oyuncunun IBAN'ı. withdrawal_account_name ile birlikte gönderilebilir.
withdrawal_info String Papara için ✓ Papara hesap bilgisi. Havale ve crypto için alternatif bilgi alanıdır.
withdrawal_crypto_address String Crypto için ✓ Oyuncunun crypto cüzdan adresi.

Havale İstek Örneği

curl -X POST https://netfinance.example.com/api/services/withdrawal \ -H "X-Api-Key: site_1234567890" \ -H "X-Secret-Key: secret_abcdefg..." \ -H "Content-Type: application/json" \ -d '{ "amount": "500.00", "user": "oyuncu123", "name": "Ahmet Yilmaz", "user_id": "player-123", "site_reference_number": "WDR-20260907-0001", "payment_method_id": "havale", "withdrawal_account_name": "Ahmet Yilmaz", "withdrawal_iban": "TR920006200519000006773400" }'

Başarılı Yanıt

✓ HTTP 200

{ "status": "success", "message": "Istek basariyla tamamlandi.", "token": "generated-withdrawal-token", "transaction_status": "pending", "approval_owner": "netfinance" }

Hatalı Yanıt

HTTP 422 { "status": "error", "message": "Validasyon hatasi", "errors": { "payment_method_id": "Desteklenmeyen yontem." } }
ℹ️ Not: Netfinance çekim talebini oluşturur; ödeme işlemi doğrudan bu API çağrısında tamamlanmaz. Son durum callback ile approved veya rejected olarak bildirilir.

🔄 Callback Mekanizması

Açıklama

Para yatırma veya çekme işlemi tamamlandığında, Netfinance sizin belirlediğiniz callback_url'e bir POST isteği gönderir.

Callback İstek Formatı

POST /your-callback-endpoint HTTP/1.1 Host: your-domain.com Content-Type: application/json { "transaction_id": 12345, "status": "approved", "transaction_type": "deposit", "amount": "500", "player_username": "oyuncu123", "created_at": "2026-08-10T14:30:00Z", "updated_at": "2026-08-10T14:32:00Z" }

Callback Yanıtı

Callback'e hızlı (< 2 saniye) ve statü kodu 200 ile yanıt vermelisiniz:

HTTP/1.1 200 OK Content-Type: application/json { "status": "ok", "message": "received" }
ℹ️ Bilgi: Callback başarısız olursa, Netfinance 5 defa yeniden deneme yapacaktır (exponential backoff).

📋 Entegrasyon Adımları

  1. Bridge Partner Kaydı
    Netfinance admin panelinde sitenizi Bridge Partner modu olarak kaydedin.
  2. API Anahtarı Alın
    Sistem tarafından verilen API key ve secret key'i güvenli bir şekilde saklayın.
  3. Callback URL Belirleyin
    Sitenizde tüm callback isteklerini işleyecek bir endpoint hazırlayın.
  4. Para Yatırma Akışı Entegre Edin
    Müşteri kendi ödeme sayfanızda paramı gönderdikten sonra Deposit API'yi bir bildirim olarak çağırın; ödeme sayfası veya IBAN gösterimi sizin tarafınızda kalır.
  5. Para Çekme Akışı Entegre Edin
    Oyuncunun çekim bilgilerini doğruladıktan sonra Withdrawal API'yi sunucunuzdan çağırın. Çekim yöntemi için is_withdrawal_active aktif olmalı ve deposit-only sağlayıcılar kullanılmamalıdır.
  6. Test Edin
    Sandbox ortamında deposit ve withdrawal işlemleri gerçekleştirerek callback mekanizmasını test edin.

⚠️ Hata Kodları

Kod Açıklama Çözüm
401 Yetkisiz - API key/secret hatalı Başlıklarınızı kontrol edin
400 Geçersiz istek - Parametre eksik veya hatalı İstek formatını kontrol edin
429 Rate limit aşıldı Bekleme süresi sonra yeniden deneyin
500 Sunucu hatası Destek ekibi ile iletişime geçin

🛠️ Best Practices

📞 Destek

Sorularınız veya teknik sorunlar için: