NosPay API Dokümantasyonu

📑 İçindekiler

🎯 Başlangıç
🔐 Kimlik Doğrulama
⚡ FAST vs HAVALE Yönlendirme (v3.0)
🏦 Bank ID Standardizasyonu
🛡️ Limit Kontrolleri (v3.0)
🔌 POST /api/external/getBank
✅ POST /api/external/proceed
💰 POST /api/external/deposit
💳 POST /api/external/withdrawal
🔍 GET /api/external/status/:ref_id
📊 POST /api/external/checkStatus
🔔 Webhook Bildirimleri
🚨 Hata Kodları

🎯 Başlangıç

NosPay API'yi entegre etmek için aşağıdaki bilgilere ihtiyacınız olacak:

Base URL: https://nospay.net/api/external

API Key (sid): Platformunuz için benzersiz tanımlayıcı (NosPay tarafından sağlanır)

API Secret: İstekleri imzalamak için gizli anahtar (NosPay tarafından sağlanır)

Webhook URL: Ödeme bildirimlerini almak için endpoint

Webhook Secret: Webhook imzalarını doğrulamak için gizli anahtar (NosPay tarafından sağlanır)

📌 Not: API Key ve Secret bilgilerinizi almak için NosPay destek ekibi ile iletişime geçiniz.

🔐 Kimlik Doğrulama

NosPay API iki farklı kimlik doğrulama yöntemi destekler:

Yöntem 1: HMAC-SHA256 İmza (getBank / proceed / checkStatus)

getBank, proceed ve checkStatus endpoint'leri için kullanılır. İmza, payload'ın (signature hariç) JSON string'i üzerinden HMAC-SHA256 ile oluşturulur.

İmza Oluşturma:
// Payload'dan signature alanını çıkar
const payloadWithoutSignature = { sid, sessionId, bank_id, amount, username, fullname };

// HMAC-SHA256 imzası oluştur
const signature = crypto
  .createHmac('sha256', API_SECRET)
  .update(JSON.stringify(payloadWithoutSignature))
  .digest('hex');

// İmzayı payload'a ekle
payloadWithoutSignature.signature = signature;

Yöntem 2: API Key + HMAC-SHA256 (deposit / withdrawal / status)

deposit, withdrawal ve status endpoint'leri için kullanılır. API Key header'da, imza body'de gönderilir.

Request Header:
X-API-Key: sizin_api_anahtariniz

İmza Oluşturma:
const crypto = require('crypto');

// Payload oluştur (imza OLMADAN)
const payload = {
  timestamp: Date.now(),
  external_ref_id: "SIPARIS-12345",
  member_name: "Ahmet Yılmaz",
  member_username: "ahmetyilmaz",
  member_id: "KULLANICI-123",
  amount: 1000
};

// HMAC-SHA256 imzası oluştur
const signature = crypto
  .createHmac('sha256', API_SECRET)
  .update(JSON.stringify(payload))
  .digest('hex');

// İmzayı payload'a ekle
payload.signature = signature;

⚠️ Önemli: İmza oluştururken payload'da signature alanı OLMAMALIDIR. İmzayı hesapladıktan sonra payload'a ekleyin. Timestamp 5 dakikadan eski olamaz.

Yöntem 3: JWT Bearer Token (Alternatif)

Deposit ve withdrawal endpoint'leri JWT Bearer token ile de kullanılabilir.

Authorization Header:
Authorization: Bearer <jwt_token>

// JWT token oluşturma (HS512 algoritması)
const jwt = require('jsonwebtoken');
const token = jwt.sign(payload, API_SECRET, { algorithm: 'HS512' });

⚡ FAST vs HAVALE Otomatik Yönlendirme (v3.0)

✨ v3.0 Yeni Özellik: Sistem artık tutara göre otomatik olarak FAST veya HAVALE yönlendirmesi yapar.

📌 Yönlendirme Kuralları:

• 0 - 100.000 TL arası: ⚡ FAST — bank_id yok sayılır, kullanıcının TÜM aktif IBAN'larından rastgele seçim yapılır

• 100.000 TL üzeri: 🏦 HAVALE — bank_id zorunludur, belirtilen bankadaki hesaplardan seçim yapılır

Özellik	⚡ FAST (≤ 100.000 TL)	🏦 HAVALE (> 100.000 TL)
bank_id	Yok sayılır (gönderilse bile)	Zorunlu (1-45 arası)
Hesap Seçimi	Kullanıcının tüm aktif IBAN'larından rastgele	Belirtilen bankadaki aktif hesaplardan
Dağıtım	Round-robin (kullanıcı bazlı)	Round-robin (kullanıcı + banka bazlı)
Yanıtta transferType	"FAST"	"HAVALE"

⚠️ Önemli: 100.000 TL üzeri HAVALE işlemlerinde bank_id gönderilmezse, sistem tüm aktif bankaları sırayla deneyecektir. Ancak en iyi sonuç için bank_id göndermeniz önerilir.

🏦 Bank ID Standardizasyonu

📌 Not: Güncel banka listesini GET /api/external/banks endpoint'inden alabilirsiniz.

Standard Banka Listesi

1 İş Bankası

2 Garanti Bankası

3 Akbank

4 Vakıfbank

5 Ziraat Bankası

6 Yapı Kredi

7 Denizbank

8 Finansbank / Enpara

9 Şekerbank

10 Kuveyt Türk

11 TEB

12 Albaraka Türk

13 Halkbank

14 PTT

15 Odea Bank

16 Turkiye Finans

19 Fibabank

20 ING Bank

21 Vakıf Katılım

22 NKolay Bank

23 FAST EFT

24 PayCell

40 Payfix

41 HSBC

42 Ziraat Katılım

43 Papara

44 QNB Finansbank

45 Enpara

🛡️ Limit Kontrolleri (v3.0)

✨ v3.0 Yeni Özellik: Hem yatırım hem de çekim işlemleri artık Genel Ayarlar'dan belirlenen min/max limitlere tabidir.

Yatırım (Deposit) Limitleri

Yatırım talepleri iki seviyede kontrol edilir:

• Global Limitler: Genel Ayarlar'dan belirlenen deposit_min_limit ve deposit_max_limit

• Kullanıcı Bazlı Limitler: Her kullanıcıya özel user_deposit_min_limit ve user_deposit_max_limit

• Kullanıcı limitleri global limitleri aşamaz (en kısıtlayıcı olan geçerlidir)

Çekim (Withdrawal) Limitleri

Çekim talepleri global seviyede kontrol edilir:

• Global Limitler: Genel Ayarlar'dan belirlenen withdrawal_min_limit ve withdrawal_max_limit

• Limit 0 olarak ayarlanmışsa o yönde kontrol devre dışıdır (sınırsız)

Limit Aşımı Hata Yanıtları

Yatırım Limit Aşımı:
{
  "success": false,
  "error": "Minimum yatırım tutarı 2.000 TL'dir. Gönderilen: 500 TL",
  "code": "AMOUNT_BELOW_MIN_LIMIT",
  "limits": { "min": 2000, "max": 500000 }
}

Çekim Limit Aşımı:
{
  "success": false,
  "error": "Minimum çekim tutarı 1.000 TL'dir. Gönderilen: 200 TL",
  "code": "WITHDRAWAL_BELOW_MIN_LIMIT",
  "limits": { "min": 1000, "max": 300000 }
}

🔌 POST /api/external/getBank

Yatırım işlemi için banka hesabı alın. Sistem tutara göre otomatik FAST/HAVALE yönlendirmesi yapar.

POST https://nospay.net/api/external/getBank

📌 Kimlik Doğrulama: HMAC-SHA256 imza yöntemi kullanılır. signature = hmac_sha256(JSON.stringify(payload_without_signature), api_secret)

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
sid	string	Zorunlu	Site ID (API Key - NosPay tarafından sağlanır)
signature	string	Zorunlu	HMAC-SHA256 imzası: hmac_sha256(JSON.stringify(payload_without_signature), api_secret)
sessionId	string	Zorunlu	Benzersiz işlem ID'si (Transaction ID)
bank_id	integer	Zorunlu	Standart banka ID'si (1-45). ≤100K TL işlemlerde FAST olarak yok sayılır
amount	number	Zorunlu	İşlem tutarı (TL). Yatırım limitlerine tabi
username	string	Opsiyonel*	Kullanıcı adı (member_username yoksa kullanın)
fullname	string	Opsiyonel*	Kullanıcı tam adı (member_name yoksa kullanın)
member_username	string	Opsiyonel*	username alternatifi
member_name	string	Opsiyonel*	fullname alternatifi
member_id	string	Opsiyonel	Üye ID'si (varsayılan: username)

⚠️ Önemli: Ya (username + fullname) YA DA (member_username + member_name) sağlanmalıdır.

Başarılı Yanıt

JSON Response (FAST örneği - ≤100K TL):
{
  "error": null,
  "data": {
    "sessionId": "TXN-12345",
    "walletName": "Ahmet Yılmaz",
    "walletNumber": "TR330006100519786457841326",
    "bankName": "İş Bankası",
    "bankId": 1,
    "userId": 5,
    "accountId": 12,
    "transferType": "FAST"
  }
}

JSON Response (HAVALE örneği - >100K TL):
{
  "error": null,
  "data": {
    "sessionId": "TXN-67890",
    "walletName": "Mehmet Demir",
    "walletNumber": "TR110006200000000012345678",
    "bankName": "Garanti Bankası",
    "bankId": 2,
    "userId": 3,
    "accountId": 8,
    "transferType": "HAVALE"
  }
}

JavaScript Örneği

JavaScript Implementation:
const crypto = require('crypto');
const axios = require('axios');

// API Kimlik Bilgileri (NosPay tarafından sağlanır)
const SID = 'sizin_api_anahtariniz';
const API_SECRET = 'sizin_api_secret_anahtariniz';
const API_URL = 'https://nospay.net/api/external/getBank';

async function getBank(bankId, amount, username, fullname) {
  const sessionId = `TXN-${Date.now()}`;
  
  // Payload oluştur (signature OLMADAN)
  const payload = {
    sid: SID,
    sessionId: sessionId,
    bank_id: bankId,
    amount: amount,
    username: username,
    fullname: fullname
  };
  
  // HMAC-SHA256 imzası oluştur
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  // İmzayı payload'a ekle
  payload.signature = signature;
  
  try {
    const response = await axios.post(API_URL, payload);
    
    if (response.data.error) {
      console.error('Error:', response.data.error);
      return null;
    }
    
    const data = response.data.data;
    console.log(`Transfer Tipi: ${data.transferType}`);
    console.log(`Bank: ${data.bankName} (ID: ${data.bankId})`);
    console.log(`IBAN: ${data.walletNumber}`);
    console.log(`Hesap Sahibi: ${data.walletName}`);
    return data;
  } catch (error) {
    console.error('Request error:', error.message);
    return null;
  }
}

// Örnek: 50,000 TL (FAST olarak yönlendirilir)
getBank(1, 50000, 'user123', 'Ahmet Yılmaz');

// Örnek: 150,000 TL (HAVALE olarak yönlendirilir)
getBank(2, 150000, 'user456', 'Mehmet Demir');

Hata Yanıtları

Hata	Açıklama
`{"error": "Wrong sid"}`	Geçersiz sid veya platform aktif değil
`{"error": "Wrong signature"}`	Geçersiz HMAC-SHA256 imzası
`{"error": "Wrong bank_id"}`	bank_id parametresi eksik
`{"error": "Invalid bank_id (must be 1-45)"}`	bank_id geçerli aralık dışında
`{"error": "Wrong amount"}`	amount parametresi eksik veya geçersiz
`{"error": "Minimum yatırım tutarı X TL'dir..."}`	Tutar, yatırım alt limitinin altında
`{"error": "Maksimum yatırım tutarı X TL'dir..."}`	Tutar, yatırım üst limitinin üstünde
`{"error": "Duplicated Process"}`	sessionId zaten kullanılmış
`{"error": "Bekleyen Talebiniz Bulunmaktadır"}`	Kullanıcının bekleyen işlemi var (30 dk içinde)
`{"error": "Invalid bank_id or bank not active"}`	İstenen banka bulunamadı veya aktif değil (sadece HAVALE)
`{"error": "No available user with sufficient limit"}`	Yeterli günlük limiti olan kullanıcı yok
`{"error": "Rate limit exceeded..."}`	Platform veya global rate limit aşıldı

✅ POST /api/external/proceed

getBank ile alınan hesap bilgilerine transfer yapıldıktan sonra işlemi onaylamak için kullanılır. Bu endpoint, pending transaction'ı deposit request'e dönüştürür.

POST https://nospay.net/api/external/proceed

📌 Kimlik Doğrulama: HMAC-SHA256 imza yöntemi kullanılır (getBank ile aynı).

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
sid	string	Zorunlu	Site ID (API Key)
signature	string	Zorunlu	HMAC-SHA256 imzası
sessionId	string	Zorunlu	getBank'tan dönen sessionId (Transaction ID)
amount	number	Zorunlu	Transfer edilen tutar (TL)
note	string	Opsiyonel	Ek notlar

Başarılı Yanıt

Success Response:
{
  "error": ""
}

JavaScript Örneği

JavaScript Implementation:
const crypto = require('crypto');
const axios = require('axios');

const SID = 'sizin_api_anahtariniz';
const API_SECRET = 'sizin_api_secret_anahtariniz';
const API_URL = 'https://nospay.net/api/external/proceed';

async function proceedTransaction(sessionId, amount) {
  // Payload oluştur (signature OLMADAN)
  const payload = {
    sid: SID,
    sessionId: sessionId,
    amount: amount
  };
  
  // HMAC-SHA256 imzası oluştur
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  payload.signature = signature;
  
  try {
    const response = await axios.post(API_URL, payload);
    
    if (response.data.error === '') {
      console.log('✅ İşlem başarıyla onaylandı!');
      return true;
    } else {
      console.error('Hata:', response.data.error);
      return false;
    }
  } catch (error) {
    console.error('Request error:', error.message);
    return false;
  }
}

// getBank'tan dönen sessionId ile kullanım
proceedTransaction('TXN-12345', 50000);

Hata Yanıtları

Hata	Açıklama
`{"error": "Wrong sessionId (Transaction ID)"}`	sessionId parametresi eksik
`{"error": "Wrong amount"}`	amount parametresi eksik
`{"error": "Transaction not found"}`	Belirtilen sessionId ile pending işlem bulunamadı
`{"error": "Transaction already processed"}`	İşlem zaten işlenmiş
`{"error": "Timeout exceeded ( 30 Mins)"}`	İşlem süresi dolmuş (30 dakika)
`{"error": "Minimum yatırım tutarı X TL'dir..."}`	Tutar, yatırım limitlerinin dışında

getBank + proceed Akışı

1. Adım: /getBank endpoint'ini çağırın → Banka hesap bilgilerini alın

2. Adım: Kullanıcıya IBAN, hesap sahibi ve banka bilgilerini gösterin

3. Adım: Kullanıcı parayı transfer etsin

4. Adım: /proceed endpoint'ini çağırarak işlemi onaylayın

5. Adım: NosPay admin ekibi işlemi kontrol eder → Webhook bildirimi gelir

⚠️ Süre Sınırı: getBank'tan sonra 30 dakika içinde proceed çağrılmalıdır. Aksi halde işlem otomatik olarak "expired" olur.

💰 POST /api/external/deposit

📌 Not: Bu endpoint, getBank/proceed akışına alternatif olarak doğrudan yatırım talebi oluşturur. Yanıtta hesap bilgileri (account_details) de döner.

POST https://nospay.net/api/external/deposit

📌 Kimlik Doğrulama: X-API-Key header + HMAC-SHA256 imza yöntemi veya JWT Bearer token kullanılır.

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
timestamp	number	Zorunlu	Unix timestamp (milisaniye cinsinden)
external_ref_id	string	Zorunlu	Platformunuzdan benzersiz referans ID
member_name	string	Zorunlu	Oyuncunun tam adı
member_username	string	Zorunlu	Oyuncunun kullanıcı adı
member_id	string	Zorunlu	Platformunuzdan benzersiz oyuncu ID
amount	number	Zorunlu	Yatırım tutarı (TL). Yatırım limitlerine tabi
bank_id	integer	Opsiyonel	Banka ID (1-45). >100K TL HAVALE için kullanılır. ≤100K FAST'ta yok sayılır
sender_name	string	Opsiyonel	Para gönderen kişinin adı
sender_iban	string	Opsiyonel	Gönderenin IBAN'ı
note	string	Opsiyonel	Ek notlar
signature	string	Zorunlu	HMAC-SHA256 imzası

Örnek İstek (cURL)

cURL Command:
curl -X POST https://nospay.net/api/external/deposit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sizin_api_anahtariniz" \
  -d '{
    "timestamp": 1705420800000,
    "external_ref_id": "SIPARIS-12345",
    "member_name": "Ahmet Yılmaz",
    "member_username": "ahmetyilmaz",
    "member_id": "KULLANICI-123",
    "amount": 1000,
    "sender_name": "Ahmet Yılmaz",
    "note": "Oyun platformundan yatırım",
    "signature": "a1b2c3d4e5f6..."
  }'

Başarılı Yanıt

Success Response:
{
  "success": true,
  "ref_id": "SIPARIS-12345",
  "external_ref_id": "SIPARIS-12345",
  "status": "pending",
  "amount": 1000,
  "message": "Yatırım talebi başarıyla oluşturuldu",
  "created_at": "2024-01-16T12:00:00.000Z",
  "account_details": {
    "bank_name": "İş Bankası",
    "account_holder": "Ahmet Yılmaz",
    "iban": "TR330006100519786457841326",
    "bank_id": 1,
    "transfer_note": "SIPARIS-12345"
  },
  "user_id": 5,
  "account_id": 12
}

Yanıt Parametreleri Açıklaması

Parametre	Tip	Açıklama
`ref_id`	string	NosPay referans numarası (external_ref_id ile aynı)
`account_details.bank_name`	string	Para gönderilecek bankanın adı
`account_details.account_holder`	string	Hesap sahibinin tam adı
`account_details.iban`	string	Para gönderilecek IBAN numarası
`account_details.bank_id`	number	Banka ID'si (1-45 arası)
`account_details.transfer_note`	string	Açıklama kısmına yazılacak referans numarası

⚠️ Kullanıcıya Gösterim: account_details içindeki bilgiler kullanıcıya mutlaka gösterilmelidir. Kullanıcı bu IBAN'a para göndermelidir.

JavaScript Örneği

JavaScript Implementation:
const axios = require('axios');
const crypto = require('crypto');

const API_KEY = 'sizin_api_anahtariniz';
const API_SECRET = 'sizin_api_secret_anahtariniz';
const API_URL = 'https://nospay.net/api/external/deposit';

async function yatirimTalebiOlustur() {
  const payload = {
    timestamp: Date.now(),
    external_ref_id: `SIPARIS-${Date.now()}`,
    member_name: 'Ahmet Yılmaz',
    member_username: 'ahmetyilmaz',
    member_id: 'KULLANICI-123',
    amount: 1000,
    sender_name: 'Ahmet Yılmaz'
  };

  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');

  payload.signature = signature;

  try {
    const response = await axios.post(API_URL, payload, {
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
      }
    });
    
    const accountInfo = response.data.account_details;
    
    console.log('✅ Yatırım talebi başarıyla oluşturuldu!');
    console.log(`📋 Referans No: ${response.data.ref_id}`);
    console.log(`🏦 Banka: ${accountInfo.bank_name}`);
    console.log(`👤 Hesap Sahibi: ${accountInfo.account_holder}`);
    console.log(`💳 IBAN: ${accountInfo.iban}`);
    console.log(`📝 Açıklama: ${accountInfo.transfer_note}`);
    
    return response.data;
  } catch (error) {
    console.error('Hata:', error.response?.data || error.message);
    throw error;
  }
}

yatirimTalebiOlustur();

💳 POST /api/external/withdrawal

✨ v3.0 Güncelleme: Çekim talepleri artık Genel Ayarlar'dan belirlenen min/max limitlere tabidir.

POST https://nospay.net/api/external/withdrawal

📌 Kimlik Doğrulama: X-API-Key header + HMAC-SHA256 imza yöntemi veya JWT Bearer token kullanılır.

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
timestamp	number	Zorunlu	Unix timestamp (milisaniye cinsinden)
external_ref_id	string	Zorunlu	Platformunuzdan benzersiz referans ID
member_name	string	Zorunlu	Oyuncunun tam adı
member_username	string	Zorunlu	Oyuncunun kullanıcı adı
member_id	string	Zorunlu	Platformunuzdan benzersiz oyuncu ID
member_iban	string	Zorunlu	Çekim için oyuncunun IBAN numarası
amount	number	Zorunlu	Çekim tutarı (TL). Çekim limitlerine tabi
note	string	Opsiyonel	Ek notlar
signature	string	Zorunlu	HMAC-SHA256 imzası

🛡️ Limit Kontrolü: Çekim tutarı, Genel Ayarlar'dan belirlenen withdrawal_min_limit ve withdrawal_max_limit değerlerine göre kontrol edilir. Limit dışı tutarlar reddedilir.

Örnek İstek (cURL)

cURL Command:
curl -X POST https://nospay.net/api/external/withdrawal \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sizin_api_anahtariniz" \
  -d '{
    "timestamp": 1705420800000,
    "external_ref_id": "CEKIM-67890",
    "member_name": "Mehmet Demir",
    "member_username": "mehmetdemir",
    "member_id": "KULLANICI-456",
    "member_iban": "TR330006100519786457841326",
    "amount": 500,
    "note": "Çekim talebi",
    "signature": "x1y2z3a4b5c6..."
  }'

Başarılı Yanıt

Success Response:
{
  "success": true,
  "ref_id": "CEKIM-67890",
  "external_ref_id": "CEKIM-67890",
  "status": "pending",
  "amount": 500,
  "message": "Withdrawal request created successfully",
  "created_at": "2024-01-16T12:00:00.000Z"
}

Limit Aşımı Hata Yanıtı

Limit Error Response:
{
  "success": false,
  "error": "Minimum çekim tutarı 1.000 TL'dir. Gönderilen: 200 TL",
  "code": "WITHDRAWAL_BELOW_MIN_LIMIT",
  "limits": {
    "min": 1000,
    "max": 300000
  }
}

JavaScript Örneği

JavaScript Implementation:
const axios = require('axios');
const crypto = require('crypto');

const API_KEY = 'sizin_api_anahtariniz';
const API_SECRET = 'sizin_api_secret_anahtariniz';
const API_URL = 'https://nospay.net/api/external/withdrawal';

async function cekimTalebiOlustur() {
  const payload = {
    timestamp: Date.now(),
    external_ref_id: `CEKIM-${Date.now()}`,
    member_name: 'Mehmet Demir',
    member_username: 'mehmetdemir',
    member_id: 'KULLANICI-456',
    member_iban: 'TR330006100519786457841326',
    amount: 500
  };

  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');

  payload.signature = signature;

  try {
    const response = await axios.post(API_URL, payload, {
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
      }
    });
    
    if (response.data.success) {
      console.log('✅ Çekim talebi başarıyla oluşturuldu!');
      console.log(`📋 Referans No: ${response.data.ref_id}`);
    } else {
      // Limit hatası kontrolü
      if (response.data.code === 'WITHDRAWAL_BELOW_MIN_LIMIT' || 
          response.data.code === 'WITHDRAWAL_ABOVE_MAX_LIMIT') {
        console.error(`🛡️ Limit hatası: ${response.data.error}`);
        console.error(`Limitler: Min=${response.data.limits.min}, Max=${response.data.limits.max}`);
      } else {
        console.error('Hata:', response.data.error);
      }
    }
    
    return response.data;
  } catch (error) {
    console.error('Hata:', error.response?.data || error.message);
    throw error;
  }
}

cekimTalebiOlustur();

🔍 GET /api/external/status/:ref_id

İşlem durumunu ref_id ile sorgulayın. Hem yatırım hem de çekim işlemlerini kontrol eder.

GET https://nospay.net/api/external/status/:ref_id

📌 Kimlik Doğrulama: X-API-Key header + HMAC-SHA256 imza yöntemi veya JWT Bearer token kullanılır.

Başarılı Yanıt

Success Response:
{
  "success": true,
  "type": "deposit",
  "ref_id": "SIPARIS-12345",
  "external_ref_id": "SIPARIS-12345",
  "status": "approved",
  "amount": 1000,
  "approved_amount": 1000,
  "approved_by": "admin",
  "approved_at": "2024-01-16T12:30:00.000Z",
  "rejection_reason": null,
  "created_at": "2024-01-16T12:00:00.000Z"
}

📊 POST /api/external/checkStatus

İşlem durumunu processId ve type ile sorgulayın. getBank/proceed akışı için uyumlu endpoint.

POST https://nospay.net/api/external/checkStatus

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
processId	string	Zorunlu	İşlem ID'si (external_ref_id)
sid	string	Zorunlu	Site ID (API Key)
type	string	Zorunlu	"havale" (yatırım) veya "withdraw" (çekim)
signature	string	Zorunlu	HMAC-SHA256 imzası: hmac_sha256(JSON.stringify({processId, sid, type}), api_secret)

Başarılı Yanıt

Success Response:
// Onaylanmış işlem
{
  "hasError": false,
  "message": "Process Status: Succeeded",
  "errorCode": 0,
  "statusCode": "1"
}

// Reddedilmiş işlem
{
  "hasError": false,
  "message": "Process Status: Cancelled",
  "errorCode": 0,
  "statusCode": "0"
}

// Bekleyen işlem
{
  "hasError": false,
  "message": "Process Status: Pending",
  "errorCode": 0,
  "statusCode": "9"
}

Status Kodları

statusCode	Durum	Açıklama
1	Succeeded (Başarılı)	İşlem onaylanmış
0	Cancelled (İptal)	İşlem reddedilmiş
9	Pending (Bekliyor)	İşlem henüz işlenmemiş
999	Error (Hata)	İşlem bulunamadı veya hata oluştu

JavaScript Örneği

JavaScript Implementation:
const crypto = require('crypto');
const axios = require('axios');

const SID = 'sizin_api_anahtariniz';
const API_SECRET = 'sizin_api_secret_anahtariniz';
const API_URL = 'https://nospay.net/api/external/checkStatus';

async function checkStatus(processId, type) {
  const payload = { processId, sid: SID, type };
  
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  payload.signature = signature;
  
  try {
    const response = await axios.post(API_URL, payload);
    
    if (!response.data.hasError) {
      console.log(`Status: ${response.data.message}`);
      console.log(`Code: ${response.data.statusCode}`);
      // statusCode: "1" = Başarılı, "0" = İptal, "9" = Bekliyor
    } else {
      console.error('Hata:', response.data.message);
    }
    
    return response.data;
  } catch (error) {
    console.error('Request error:', error.message);
  }
}

// Yatırım durumu sorgula
checkStatus('SIPARIS-12345', 'havale');

// Çekim durumu sorgula
checkStatus('CEKIM-67890', 'withdraw');

🔔 Webhook Bildirimleri

NosPay, admin ekibimiz bir yatırım veya çekim talebini onayladığında veya reddettiğinde yapılandırılmış endpoint'inize webhook bildirimi gönderir.

Webhook Payload Yapısı

Webhook Payload:
{
  "event": "deposit.approved" | "deposit.rejected" | "withdrawal.approved" | "withdrawal.rejected",
  "ref_id": "SIPARIS-12345",
  "external_ref_id": "SIPARIS-12345",
  "status": "approved" | "rejected",
  "amount": 1000,
  "approved_amount": 1000,
  "rejection_reason": "Red nedeni (reddedilmişse)",
  "timestamp": 1705420800000,
  "signature": "webhook_imzasi_buraya"
}

Webhook İmzasını Doğrulama

JavaScript - İmza Doğrulama:
const crypto = require('crypto');

function webhookImzasiniDogrula(payload, signature, webhookSecret) {
  // İmza olmadan payload oluştur
  const payloadWithoutSignature = { ...payload };
  delete payloadWithoutSignature.signature;
  
  // Beklenen imzayı hesapla
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(JSON.stringify(payloadWithoutSignature))
    .digest('hex');
  
  // Güvenli karşılaştırma yap
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js webhook handler örneği
app.post('/webhook/nospay', (req, res) => {
  const payload = req.body;
  const signature = payload.signature;
  
  if (!webhookImzasiniDogrula(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  switch (payload.event) {
    case 'deposit.approved':
      console.log(`✅ Yatırım onaylandı: ${payload.ref_id}, Tutar: ${payload.approved_amount}`);
      // Kullanıcı bakiyesini güncelle
      break;
    case 'deposit.rejected':
      console.log(`❌ Yatırım reddedildi: ${payload.ref_id}, Neden: ${payload.rejection_reason}`);
      break;
    case 'withdrawal.approved':
      console.log(`✅ Çekim onaylandı: ${payload.ref_id}, Tutar: ${payload.approved_amount}`);
      break;
    case 'withdrawal.rejected':
      console.log(`❌ Çekim reddedildi: ${payload.ref_id}, Neden: ${payload.rejection_reason}`);
      break;
  }
  
  // 200 OK ile yanıt ver (10 saniye içinde)
  res.status(200).json({ received: true });
});

⚠️ Önemli: Webhook endpoint'iniz 10 saniye içinde HTTP 200 ile yanıt vermelidir. Başarısız webhook'lar üstel geri çekilme ile 3 kereye kadar yeniden denenecektir.

🚨 Hata Kodları

Kimlik Doğrulama Hataları

Kod	Açıklama	Çözüm
AUTH_MISSING_KEY	Header'da API key sağlanmamış	İsteğinize X-API-Key header'ı ekleyin
AUTH_INVALID_KEY	Geçersiz API key	API key kimlik bilgilerinizi kontrol edin
AUTH_MISSING_PARAMS	Timestamp veya imza eksik	Request body'ye timestamp ve signature ekleyin
AUTH_INVALID_SIGNATURE	Geçersiz istek imzası	API Secret kullanarak imza oluşturmayı doğrulayın
AUTH_INVALID_TOKEN	Geçersiz JWT token	JWT token'ınızı HS512 algoritması ile oluşturduğunuzdan emin olun
AUTH_TIMESTAMP_EXPIRED	İstek timestamp'i çok eski (>5 dakika)	Güncel timestamp kullanın
AUTH_PLATFORM_INACTIVE	Platformunuz aktif değil	Hesabınızı aktifleştirmek için destek ile iletişime geçin

Validasyon Hataları

Kod	Açıklama	Çözüm
VALIDATION_ERROR	Eksik veya geçersiz zorunlu alanlar	Tüm zorunlu parametreleri kontrol edin
DUPLICATE_REF_ID	External reference ID zaten mevcut	Her istek için benzersiz external_ref_id kullanın

Limit Hataları

Kod	Açıklama	Çözüm
YENİ AMOUNT_BELOW_MIN_LIMIT	Yatırım tutarı minimum limitin altında	Yatırım tutarını artırın (yanıttaki limits.min değerine bakın)
YENİ AMOUNT_ABOVE_MAX_LIMIT	Yatırım tutarı maksimum limitin üstünde	Yatırım tutarını azaltın (yanıttaki limits.max değerine bakın)
YENİ WITHDRAWAL_BELOW_MIN_LIMIT	Çekim tutarı minimum limitin altında	Çekim tutarını artırın (yanıttaki limits.min değerine bakın)
YENİ WITHDRAWAL_ABOVE_MAX_LIMIT	Çekim tutarı maksimum limitin üstünde	Çekim tutarını azaltın (yanıttaki limits.max değerine bakın)

Sistem Hataları

Kod	Açıklama	Çözüm
RATE_LIMIT_EXCEEDED	Platform rate limit aşıldı	Yeniden denemeden önce bekleyin (yanıtta retry_after'a bakın)
GLOBAL_RATE_LIMIT_EXCEEDED	Sistem geneli rate limit aşıldı	Yeniden denemeden önce bekleyin
NO_ACCOUNTS_AVAILABLE	İşlem için aktif hesap yok	Destek ile iletişime geçin
INTERNAL_ERROR	Sunucu hatası	Destek ile iletişime geçin