Nospay API Dokümantasyonu

Nospay, güvenli ve hızlı ödeme işlemleri için geliştirilmiş modern bir API platformudur. Bu dokümantasyon, API entegrasyonu için gereken tüm bilgileri içerir.

🔐

Güvenli

JWT (HS512) ile şifrelenmiş iletişim

⚡

Hızlı

Anlık işlem bildirimleri

🌐

RESTful

Modern REST API standardı

🔄

Webhook

Otomatik callback bildirimleri

📌 Önemli: API kullanımı için öncelikle site_id ve secret_key almanız gerekmektedir. Test için sandbox ortamını kullanabilirsiniz.

Base URL

Production

https://api.nospay.com/v1

Sandbox (Test)

https://sandbox-api.nospay.com/v1

🔐 Authentication

Nospay API, JWT (JSON Web Token) tabanlı authentication kullanır. Tüm istekler JWT token ile şifrelenmelidir.

Credentials

API kullanımı için size verilen bilgiler:

site_id: Sitenizin benzersiz kimliği (örn: NOSPAY_101)
secret_key: JWT şifreleme için gizli anahtar

JWT Token Oluşturma

Her API isteği için JWT token oluşturmanız gerekir:

JWT Header

{
  "alg": "HS512",
  "typ": "JWT"
}

Request Body (Payload)

{
  "site_id": "NOSPAY_101",
  "session_id": "TXN_20260114_001",
  "member_username": "player123",
  "member_fullname": "Ahmet Yılmaz",
  "amount": 500,
  "callback_url": "https://yoursite.com/callback",
  "timestamp": 1705251234
}

Token Generation (Node.js)

const jwt = require('jsonwebtoken');

const payload = {
  site_id: "NOSPAY_101",
  session_id: "TXN_20260114_001",
  member_username: "player123",
  member_fullname: "Ahmet Yılmaz",
  amount: 500,
  callback_url: "https://yoursite.com/callback",
  timestamp: Date.now()
};

const token = jwt.sign(payload, SECRET_KEY, { algorithm: 'HS512' });

// Authorization Header
const headers = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json'
};

⚠️ Güvenlik: secret_key değerini asla istemci tarafında (frontend) kullanmayın. Tüm API istekleri backend sunucunuzdan yapılmalıdır.

💰 Deposit - Banka Havalesi

Kullanıcıların banka havalesi ile yatırım yapmasını sağlar.

POST /deposit/bank/create

Yeni bir banka havalesi yatırım talebi oluşturur.

Request

Headers

Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

Request Body (JWT Encoded)

{
  "site_id": "NOSPAY_101",
  "session_id": "TXN_20260114_001",
  "member_username": "player123",
  "member_fullname": "Ahmet Yılmaz",
  "amount": 500,
  "callback_url": "https://yoursite.com/callback"
}

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "transaction_id": "NOSPAY_TXN_12345",
    "session_id": "TXN_20260114_001",
    "bank_name": "Ziraat Bankası",
    "account_holder": "Nospay Ödeme A.Ş.",
    "iban": "TR12 3456 7890 1234 5678 9012 34",
    "amount": 500,
    "status": "pending",
    "expires_at": "2026-01-14T18:30:00Z",
    "created_at": "2026-01-14T17:00:00Z"
  }
}

Parameters

Parameter	Type	Required	Description
`site_id`	string	✅	Sitenizin benzersiz kimliği
`session_id`	string	✅	İşlem kimliği (benzersiz olmalı)
`member_username`	string	✅	Kullanıcı adı
`member_fullname`	string	✅	Kullanıcının tam adı
`amount`	number	✅	Yatırım miktarı (TRY)
`callback_url`	string	✅	İşlem sonucu bildirim URL'i

⚡ Deposit - Fast Havale (2 Adımlı)

Fast Havale ile hızlı yatırım işlemi. İki adımdan oluşur:

Init: Banka hesap bilgilerini al
Confirm: Kullanıcı transferi yaptıktan sonra onayla

💡 Not: Fast Havale işlemleri 30 dakika içinde tamamlanmalıdır. Aksi takdirde işlem otomatik iptal edilir.

Step 1: Get Bank Account

POST /deposit/fast-havale/init

Kullanıcıya gösterilecek banka hesap bilgilerini alır.

Request Body

{
  "site_id": "NOSPAY_101",
  "session_id": "TXN_001",
  "member_username": "player123",
  "member_fullname": "Ahmet Yılmaz",
  "amount": 500,
  "token": "a1b2c3d4e5f6..."
}

🔐 Token: token = md5(session_id + secret_key)

Response

{
  "error": null,
  "data": {
    "session_id": "TXN_001",
    "bank_name": "Ziraat Bankası",
    "account_holder": "Nospay Ödeme A.Ş.",
    "iban": "TR12 3456 7890 1234 5678 9012 34",
    "amount": 500,
    "expires_at": "2026-01-14T18:30:00Z"
  }
}

Step 2: Confirm Transfer

POST /deposit/fast-havale/confirm

Kullanıcı transferi yaptıktan sonra işlemi onaylar.

Request Body

{
  "site_id": "NOSPAY_101",
  "session_id": "TXN_001",
  "amount": 500,
  "sender_name": "Ahmet Yılmaz",
  "sender_iban": "TR98 7654 3210 9876 5432 1098 76",
  "note": "Opsiyonel not",
  "token": "a1b2c3d4e5f6..."
}

Response

{
  "error": null,
  "message": "Transfer confirmed, waiting for approval"
}

💸 Withdraw - Banka Çekimi

Kullanıcıların banka hesabına para çekmesini sağlar.

POST /withdraw/bank/create

Yeni bir banka çekim talebi oluşturur.

Request

Headers

Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

Request Body (JWT Encoded)

{
  "site_id": "NOSPAY_101",
  "session_id": "WTH_20260114_001",
  "member_username": "player123",
  "member_fullname": "Ahmet Yılmaz",
  "amount": 300,
  "iban": "TR98 7654 3210 9876 5432 1098 76",
  "bank_name": "Ziraat Bankası"
}

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "transaction_id": "NOSPAY_WTH_67890",
    "session_id": "WTH_20260114_001",
    "status": "pending",
    "amount": 300,
    "iban": "TR98 7654 3210 9876 5432 1098 76",
    "bank_name": "Ziraat Bankası",
    "estimated_time": "1-3 hours",
    "created_at": "2026-01-14T17:00:00Z"
  }
}

🔔 Callbacks (Webhooks)

İşlem sonuçları otomatik olarak belirlediğiniz callback_url adresine gönderilir.

📌 Önemli: Callback URL'iniz POST isteklerini kabul etmeli ve 200 OK yanıtı dönmelidir. Aksi takdirde 3 kez tekrar deneme yapılır.

Callback Request

POST {your_callback_url}

Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

Callback Payload (JWT Encoded)

{
  "transaction_id": "NOSPAY_TXN_12345",
  "site_id": "NOSPAY_101",
  "session_id": "TXN_20260114_001",
  "status": "1",
  "type": "deposit",
  "method": "bank",
  "member_username": "player123",
  "member_fullname": "Ahmet Yılmaz",
  "amount": 500,
  "timestamp": "2026-01-14T17:45:30Z"
}

Status Codes

Code	Status	Description
`0`	Cancelled	İşlem iptal edildi
`1`	Success	İşlem başarılı
`9`	Pending	İşlem beklemede
`999`	Unknown	Bilinmeyen durum

Expected Response

Your Server Response

{
  "received": true
}

📊 Status Check

Herhangi bir işlemin durumunu manuel olarak sorgulayabilirsiniz.

POST /status/check

İşlem durumunu sorgular.

Request Body

{
  "site_id": "NOSPAY_101",
  "session_id": "TXN_20260114_001",
  "type": "deposit",
  "token": "a1b2c3d4e5f6..."
}

🔐 Token: token = md5(secret_key + session_id + type)

Response

{
  "hasError": false,
  "message": "Transaction approved",
  "errorCode": 0,
  "statusCode": "1",
  "data": {
    "transaction_id": "NOSPAY_TXN_12345",
    "amount": 500,
    "status": "approved",
    "created_at": "2026-01-14T17:00:00Z",
    "updated_at": "2026-01-14T17:45:30Z"
  }
}

⚠️ Error Codes

API hata kodları ve açıklamaları:

Error Code	HTTP Status	Message	Description
`0`	200	No Error	Başarılı işlem
`400`	400	Bad Request	Eksik veya hatalı parametreler
`401`	401	Unauthorized	Geçersiz JWT token veya site_id
`404`	404	Not Found	Site veya işlem bulunamadı
`405`	405	Transaction Not Found	İşlem bulunamadı
`406`	406	Invalid Parameters	Geçersiz parametreler
`409`	409	Duplicate Transaction	Aynı session_id ile işlem zaten mevcut
`429`	429	Too Many Requests	Rate limit aşıldı (max 100 req/min)
`500`	500	Internal Server Error	Sunucu hatası

Error Response Format

Error Response

{
  "success": false,
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "details": "Invalid JWT token"
  }
}

💻 Code Examples

Farklı programlama dillerinde örnek kullanımlar:

Node.js Example

deposit_example.js

const jwt = require('jsonwebtoken');
const axios = require('axios');

const SITE_ID = 'NOSPAY_101';
const SECRET_KEY = 'your_secret_key_here';
const API_URL = 'https://api.nospay.com/v1';

async function createDeposit(username, fullname, amount) {
  // Create JWT payload
  const payload = {
    site_id: SITE_ID,
    session_id: `TXN_${Date.now()}`,
    member_username: username,
    member_fullname: fullname,
    amount: amount,
    callback_url: 'https://yoursite.com/callback',
    timestamp: Date.now()
  };

  // Sign JWT token
  const token = jwt.sign(payload, SECRET_KEY, { algorithm: 'HS512' });

  // Make API request
  try {
    const response = await axios.post(`${API_URL}/deposit/bank/create`, {}, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });

    console.log('Deposit created:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}

// Usage
createDeposit('player123', 'Ahmet Yılmaz', 500);

PHP Example

deposit_example.php

<?php
require 'vendor/autoload.php';
use Firebase\JWT\JWT;

$SITE_ID = 'NOSPAY_101';
$SECRET_KEY = 'your_secret_key_here';
$API_URL = 'https://api.nospay.com/v1';

function createDeposit($username, $fullname, $amount) {
    global $SITE_ID, $SECRET_KEY, $API_URL;
    
    // Create JWT payload
    $payload = [
        'site_id' => $SITE_ID,
        'session_id' => 'TXN_' . time(),
        'member_username' => $username,
        'member_fullname' => $fullname,
        'amount' => $amount,
        'callback_url' => 'https://yoursite.com/callback',
        'timestamp' => time()
    ];
    
    // Sign JWT token
    $token = JWT::encode($payload, $SECRET_KEY, 'HS512');
    
    // Make API request
    $ch = curl_init($API_URL . '/deposit/bank/create');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$result = createDeposit('player123', 'Ahmet Yılmaz', 500);
print_r($result);
?>

Python Example

deposit_example.py

import jwt
import requests
import time

SITE_ID = 'NOSPAY_101'
SECRET_KEY = 'your_secret_key_here'
API_URL = 'https://api.nospay.com/v1'

def create_deposit(username, fullname, amount):
    # Create JWT payload
    payload = {
        'site_id': SITE_ID,
        'session_id': f'TXN_{int(time.time())}',
        'member_username': username,
        'member_fullname': fullname,
        'amount': amount,
        'callback_url': 'https://yoursite.com/callback',
        'timestamp': int(time.time())
    }
    
    # Sign JWT token
    token = jwt.encode(payload, SECRET_KEY, algorithm='HS512')
    
    # Make API request
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    
    response = requests.post(f'{API_URL}/deposit/bank/create', headers=headers)
    return response.json()

# Usage
result = create_deposit('player123', 'Ahmet Yılmaz', 500)
print(result)