NoxPay Geliştirici Belgeleri

Oyuncularınıza kalıcı kripto yatırım adresleri verin, gelen her ödemeyi zincirde kesinleştikten sonra TL olarak hesaplarına yazın, çekimleri kendi havuzunuzdan otomatik ödeyin.

Genel bakış

NoxPay, sizin sunucunuzda çalışan ve sadece size ait olan bir kripto ödeme sistemidir. Cüzdan anahtarları ve paranız sizde kalır; platformunuz NoxPay ile imzalı bir HTTP API üzerinden konuşur.

Desteklenen ağlar

Kurulumunuzda hangi coinlerin açık olduğunu her zaman GET /v1/assets söyler; coinleri koda yazmayın.

Akış

1. Oyuncu Para Yatır → Kripto'yu açar. Platformunuz NoxPay'den oyuncunun adresini ister ve adresi karekoduyla gösterir.
2. Oyuncu coin gönderir. NoxPay kesinleşmiş bloğu görür, tutarı o anki kurla TL'ye çevirir.
3. NoxPay platformunuza imzalı deposit.credited bildirimi gönderir.
4. Platformunuz imzayı doğrular, kaydı NoxPay'den teyit eder ve oyuncunun bakiyesine TL tutarı bir kez yazar.
5. Oyuncu çekim ister; platformunuz bakiyeyi düşer. Yetkiliniz onaylayınca çekimi NoxPay'e gönderir.
6. NoxPay havuzdan öder ve withdrawal.completed bildirir (ödenemezse withdrawal.failed: iade edin).

Başlarken

Size verilenler

Sizden istenenler

Ortamlar

Önce test ağında (gerçek para yok) uçtan uca denenir, sonra canlıya geçilir. Her cevaptaki chain alanı ortamı söyler: "nile" test ağı, "mainnet" canlı. Test ağında oyuncu ekranında mutlaka TEST AĞI uyarısı gösterin.

Biçim kuralları

• Bütün tutarlar metin (string) olarak gelir ve gider: coin miktarı "25.000000" (coinin ondalığı kadar), TL "1229.75" (2 ondalık), kur "49.19000000" (8 ondalık). Kayan noktalı sayıya çevirmeyin.
• Saatler UTC, RFC 3339 (2026-10-29T21:44:07Z).
• Oyuncu kimliği (player_ref): 1–64 karakter [A-Za-z0-9_-], platformunuzdaki oyuncu numarası.

İstek imzası

Platformunuzdan NoxPay'e giden her istek üç başlık taşır:

canonical = timestamp + "\n" + nonce + "\n" + METHOD + "\n" + request_uri + "\n" + hex(sha256(gövde))

request_uri: yol + varsa ? ve sorgu, gönderildiği haliyle (ör. /v1/deposits?player_ref=123&site=kralbet). Gövdesiz istekte gövde boş metindir: sha256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Test vektörü

secret    = test-api-secret-0123456789abcdef0123
timestamp = 1791500000
nonce     = 0123456789abcdef0123456789abcdef
istek     = GET /v1/deposits/dep_0123456789abcdef01234567
signature = 1948cf767d5f3c75e98dfe3ff3e503c170e444095e9f5bf9fc1276d82af6f116

Node.js

import { createHash, createHmac, randomBytes } from 'crypto';

export function noxpayHeaders(secret, method, requestUri, body = '') {
  const ts = Math.floor(Date.now() / 1000).toString();
  const nonce = randomBytes(16).toString('hex');
  const bodyHash = createHash('sha256').update(body).digest('hex');
  const canonical = [ts, nonce, method, requestUri, bodyHash].join('\n');
  return {
    'X-NoxPay-Timestamp': ts,
    'X-NoxPay-Nonce': nonce,
    'X-NoxPay-Signature': createHmac('sha256', secret).update(canonical).digest('hex'),
  };
}

PHP

function noxpay_headers(string $secret, string $method, string $requestUri, string $body = ''): array {
    $ts = (string) time();
    $nonce = bin2hex(random_bytes(16));
    $canonical = implode("\n", [$ts, $nonce, $method, $requestUri, hash('sha256', $body)]);
    return [
        'X-NoxPay-Timestamp: ' . $ts,
        'X-NoxPay-Nonce: ' . $nonce,
        'X-NoxPay-Signature: ' . hash_hmac('sha256', $canonical, $secret),
    ];
}

İmza tutmazsa 401 {"error":"unauthorized"}, izinli olmayan IP'den gelirse 403 {"error":"forbidden"}. Hata cevapları bilerek ayrıntı vermez.

Coin listesi

Kurulumunuzda çalışan coinler ve her birinin yatırıma/çekime açık olup olmadığı. Para Yatır ve Para Çek ekranlarındaki seçenekleri buradan üretin; yönetim panelinde bir coin açılıp kapatılınca platformunuzda yeni sürüm gerekmez.

{"chain":"mainnet","assets":[
  {"code":"USDT","symbol":"USDT","network":"TRON","network_label":"TRC20","decimals":6,"deposit":true,"withdraw":true},
  {"code":"USDT_BSC","symbol":"USDT","network":"BSC","network_label":"BEP20","decimals":6,"deposit":true,"withdraw":true},
  {"code":"TRX","symbol":"TRX","network":"TRON","network_label":"TRON","decimals":6,"deposit":true,"withdraw":true}]}

Yatırım

Oyuncu adresi

network verilmezse TRON. site sadece çok siteli platformlarda (bkz. Çoklu site). İlk istekte adres üretilir, sonra her istekte aynısı döner.

{"address":"TWrAmidsrgkVTyDxXuGZjaRc77DiR3jh6K","network":"TRON","chain":"mainnet","assets":["USDT","TRX"],"site":"kralbet"}

• assets: o ağda şu an yatırıma açık coinler. O ağda açık coin yoksa 422 {"error":"network_unavailable"}; o ağı ekranda gösterme.
• EVM ağlarında tek adres: bir oyuncunun 0x adresi BNB Chain ve Ethereum'da aynıdır. Oyuncu yanlış EVM ağından gönderse de para kaybolmaz; hangi ağdan geldiyse o ağın asset koduyla bildirilir.
• Kapalı bir coin yine de gönderilirse para kaybolmaz: normal yatırım olarak işlenir ve bildirilir.

Kurlar

Sadece ekranda "tahmini kur" göstermek için. Yatırım, zincirde kesinleştiği andaki kurla yazılır.

{"USDT_TRY":"49.19000000","TRX_TRY":"16.38500000","fetched_at":"2026-10-29T21:24:26Z","min_deposit_try":"500.00","estimate":true}

Kur alınamıyorsa 503 {"error":"rates_unavailable"}: kur alanını gizleyin, adresi yine gösterin.

Yatırım teyidi

{"deposit_id":"dep_f3fe5b9c24410637dc9063de","site":"kralbet","player_ref":"123","asset":"USDT","amount":"25.000000",
 "txid":"eb6bdbb9522e866176c024b3cfd2d55a958e2ba3c6a4ada7cb31beceda25af0b","from_address":"TM3JF…",
 "block_time":"2026-10-29T21:25:12Z","status":"credited","rate_try":"49.19000000","amount_try":"1229.75",
 "credited_at":"2026-10-29T21:25:51Z","chain":"mainnet"}

rate_try, amount_try ve credited_at sadece status = "credited" iken gelir. Bulunamazsa 404 {"error":"not_found"}.

Yatırım geçmişi

Oyuncunun kripto yatırımları, eskiden yeniye: {"deposits":[…]}. limit 1–200 (varsayılan 50).

Bildirimler

NoxPay, bildirim adresinize POST ile JSON gönderir. Bildirimler en az bir kez teslim edilir: aynı bildirim birden çok gelebilir.

POST <bildirim adresiniz>
Content-Type: application/json
X-NoxPay-Event: deposit.credited
X-NoxPay-Delivery: 1842
X-NoxPay-Timestamp: 1791500000
X-NoxPay-Signature: hex(HMAC-SHA256(IMZA_SIRRI, timestamp + "." + ham_gövde))

{"event":"deposit.credited","deposit_id":"dep_f3fe5b9c24410637dc9063de","site":"kralbet","player_ref":"123",
 "asset":"USDT","amount":"25.000000","txid":"eb6bdbb9…","rate_try":"49.19000000",
 "amount_try":"1229.75","credited_at":"2026-10-29T21:25:51Z"}

İmza doğrulama

İmza ham gövde üzerinden doğrulanır; JSON'u ayrıştırıp yeniden üretilmiş gövdeyle değil (Express/NestJS'te ham gövdeyi saklayın, PHP'de php://input).

secret    = test-webhook-secret-0123456789abcdef
timestamp = 1791500000
body      = {"event":"deposit.credited","deposit_id":"dep_0123456789abcdef01234567","amount_try":"5174.99"}
signature = d46bd41a19efa7ae09cf3d9857dcfc6526dae12e9af9318431640df2055dc01b

Node.js

import { createHmac, timingSafeEqual } from 'crypto';

export function verifyNoxPay(secret, ts, sig, rawBody /* Buffer */) {
  const age = Math.abs(Date.now() / 1000 - Number(ts));
  if (!Number.isFinite(age) || age > 300) return false;            // ±5 dakika
  const want = createHmac('sha256', secret).update(`${ts}.`).update(rawBody).digest('hex');
  const a = Buffer.from(want), b = Buffer.from(String(sig).toLowerCase());
  return a.length === b.length && timingSafeEqual(a, b);
}

PHP

function noxpay_verify(string $secret, string $ts, string $sig, string $rawBody): bool {
    if (!ctype_digit($ts) || abs(time() - (int) $ts) > 300) {
        return false;                                                  // ±5 dakika
    }
    $want = hash_hmac('sha256', $ts . '.' . $rawBody, $secret);
    return hash_equals($want, strtolower($sig));
}

$raw = file_get_contents('php://input');
$ok  = noxpay_verify(IMZA_SIRRI, $_SERVER['HTTP_X_NOXPAY_TIMESTAMP'] ?? '', $_SERVER['HTTP_X_NOXPAY_SIGNATURE'] ?? '', $raw);

İşleme sırası (zorunlu)

1. İmzayı ve zamanı doğrula. Tutmazsa 401 dön, hiçbir şey yazma.
2. Olayı tanı: deposit.credited, withdrawal.completed ya da withdrawal.failed. Başka bir şeyse 400.
3. Teyit al: yatırımda GET /v1/deposits/{deposit_id}, çekimde GET /v1/withdrawals/{withdrawal_id}. Durum ve alanlar (site, player_ref, asset, amount, txid, amount_try) bildirimle birebir aynı olmalı. Değilse 400, yazma. Bildirimdeki tutara tek başına güvenmeyin.
4. Tek seferlik yaz: yatırımı deposit_id'yi benzersiz anahtar yaparak tek işlemde kaydedin ve bakiyeye amount_try ekleyin. Kayıt zaten varsa hiçbir şey yazmayın.
5. Yazıldıysa ya da zaten yazılmışsa 200 dön. 15 saniye içinde cevap verin.

Çekim

Temel kurallar

1. Bakiye önce düşer. Oyuncu çekim istediğinde bakiyeyi siz düşersiniz; NoxPay'e ancak yetkiliniz onaylayınca gönderirsiniz.
2. Bir çekim bir kez ödenir. Anahtar sizin çekim kimliğinizdir (withdrawal_id). Aynı kimlikle gelen her istek aynı kaydı döndürür; ikinci ödeme açılmaz.
3. İade yalnızca kesin "gönderilmedi" ile: POST 422 döndüyse ya da durum failed ise. Zaman aşımı, bağlantı hatası, 5xx ve okunamayan cevap belirsizdir: iade etmeyin, aynı istekle tekrar deneyin.
4. NoxPay failed dedikten sonra asla göndermez; completed dedikten sonra asla failed demez.

Çekim oluştur

{"withdrawal_id":"wd_8842","site":"kralbet","player_ref":"123","asset":"USDT",
 "address":"TJNHaHSDCFZREa7Mx73iNHbfriQz3BfPhw","amount_try":"1250.00"}

Durum ve çekim nesnesi

{"withdrawal_id":"wd_8842","site":"kralbet","player_ref":"123","asset":"USDT","address":"TJNHaHSDCFZREa7Mx73iNHbfriQz3BfPhw",
 "amount_try":"1250.00","rate_try":"49.18000000","amount":"25.416836","status":"completed","status_reason":null,
 "txid":"a66b073a4afed3e297484a1e6790dc4b6c6cf3d288d3ff8766559176c6bf7995","created_at":"2026-10-29T10:00:00Z",
 "completed_at":"2026-10-29T10:00:41Z","chain":"mainnet"}

404 not_found tek başına iade sebebi değildir: aynı POST'u tekrar gönderin.

amount oyuncuya gidecek coin miktarıdır (aşağı yuvarlanır). Ağ ücreti oyuncudan kesilmez.

Çekim bildirimleri

Yatırım bildirimiyle aynı adres ve imza. Bildirime göre doğrudan para hareketi yapmayın: önce GET /v1/withdrawals/{id} ile teyit edin. Bildirim kaçsa bile birkaç dakikada bir durum sorgusu aynı sonuca ulaştırır.

{"event":"withdrawal.completed","withdrawal_id":"wd_8842","site":"kralbet","player_ref":"123","asset":"USDT",
 "address":"TJNH…","amount":"25.416836","rate_try":"49.18000000","amount_try":"1250.00","txid":"a66b…","completed_at":"2026-10-29T10:00:41Z"}

{"event":"withdrawal.failed","withdrawal_id":"wd_8843","site":"kralbet","player_ref":"456","asset":"TRX",
 "amount_try":"800.00","reason":"cancelled_by_operator","failed_at":"2026-10-29T11:12:00Z"}

Çoklu site

Birden çok siteyi tek yazılımdan yönetiyorsanız hepsi NoxPay'e tek bağlantıyla bağlanır (aynı sırlar, aynı IP listesi, aynı bildirim adresi). Her istek hangi site için olduğunu site ile söyler; yönetim panelinde yatırım ve çekimler site site görülür.

• Site kodu: küçük harf, rakam, - ve _; harf ya da rakamla başlar, en çok 32 karakter (^[a-z0-9][a-z0-9_-]{0,31}$), ör. kralbet, site-42. İlk kez gönderilen kod kendiliğinden tanınır; panelde görünen adını panelden verirsiniz.
• Oyuncu kimliği site başınadır: site=a + player_ref=123 ile site=b + player_ref=123 iki ayrı oyuncudur ve iki ayrı adres alır.
• site göndermeyen istek ana sitedir; tek siteli kullanımda hiç göndermeyin. O zaman cevaplarda ve bildirimlerde de site alanı yer almaz.
• withdrawal_id bütün sitelerde benzersiz olmalı; GET /v1/deposits/{id} ve GET /v1/withdrawals/{id} site istemez.

İmza kuralı değişmez: site sorgudaysa request_uri'nin, gövdedeyse gövde özetinin parçasıdır. Geçersiz kod: adres ve geçmiş isteklerinde 400, çekimde 422 — ikisi de {"error":"invalid_site"}.

Hata kodları

Ekran önerileri

• Para Yatır → Kripto: ağ ve coin seçimi GET /v1/assets'ten; adres + karekod + kopyala; tahmini kur ve en az tutar GET /v1/rates'ten.
• Uyarılar: "Sadece seçtiğiniz ağdan gönderin; başka ağdan gönderilen para kaybolabilir.", "Bu adres size özeldir, başkasına vermeyin.", "En az tutarın altındaki gönderimler bekletilir; toplam en az tutarı geçince birlikte yüklenir."
• Para Çek → Kripto: ağ seçimi; adres ağa göre doğrulanır (TRON T…, EVM 0x…); oyuncunun kendi yatırım adresi reddedilir.
• Kripto yatırım geçmişi GET /v1/deposits ile, durumlar Türkçe etiketlerle.
• Test ağında her ekranda TEST AĞI uyarısı.

Canlıya geçiş listesi

Hepsi önce test ağında geçmeli:

• İki test vektörü (istek ve bildirim imzası) kodunuzda birebir tutuyor.
• Adres: aynı oyuncuya her istekte aynı adres; kapalı ağ ekranda gizli.
• Test yatırımı → bildirim + teyit → bakiye bir kez yazıldı; aynı bildirim ikinci kez gelince bakiye değişmedi.
• Yanlış imza ya da eski zaman damgası → 401, yazım yok.
• İmzası doğru ama tutarı kayıttan farklı bildirim → 400, yazım yok.
• Çekim: onay → ödendi → withdrawal.completed + teyit → tamamlandı.
• Çekim iptali → withdrawal.failed → iade edildi; 422 ret → iade edildi; zaman aşımı → iade edilmedi, tekrar denendi.
• Çok siteli kullanımda en az iki siteyle aynı testler; aynı oyuncu numarası iki sitede iki ayrı oyuncu.
• Raporlarınız kripto yatırımlarını ve çekimlerini görüyor.

Yönetim paneli

Kurulumunuzla birlikte size özel, kendi adınız ve logonuzla bir yönetim paneli gelir. Giriş şifre + telefondaki doğrulama koduyla yapılır; kullanıcı ekleme, roller ve yapılan her işlemin kaydı paneldedir.