WinPay API — Entegrasyon Kılavuzu

Bu belge, WinPay ödeme yöntemini kendi sitesine bağlayacak geliştiriciler içindir. Yalnızca API sözleşmesini anlatır: üç uç, imza, sonuç bildirimi, durumlar ve hatalar.

Sürüm: v1 · Taban adres: https://api.win-pay.co · English version

1. Genel bakış

WinPay bir ödeme yöntemidir: sizin adınıza tahsilat ve ödeme yapar, sonucu imzalı bir bildirimle (callback) size iletir. Üyenizin bakiyesini siz yönetirsiniz.

Yatırım: siteniz talep açar → yanıttaki payment_url adresine üyeyi yönlendirir → üye ödeme sayfasında tutarı seçer, IBAN ve QR ile transferi yapar → ödeme doğrulanınca size callback gelir → siteniz bakiyeyi artırır.

Çekim: siteniz talep açar (üyenin IBAN'ı ile) → transfer yapılır → size callback gelir → siteniz çekimi tamamlanmış işaretler.

Önemli: 201 yanıtı "para geldi/gitti" demek değildir, "talep oluşturuldu" demektir. Bakiyeyi yalnızca callback geldiğinde değiştirin.

İşlem durumu sorgulayan bir uç yoktur. Sonucu callback ile alırsınız; kaybolduğunu düşünüyorsanız aynı request_id ile talebi tekrar gönderin — mevcut işlem döner (bölüm 8).

2. Erişim bilgileri

Size verilecekler:

Sizin vermeniz gerekenler:

Güvenlik kuralları

• api_key ve api_secret yalnızca sunucunuzda durur. HTML'e, mobil uygulama paketine, tarayıcıya konmaz.
• Üç sır birbirinden farklıdır ve birbirinin yerine kullanılmaz.
• Sunucunuzun saati doğru olmalıdır (NTP) — imza zaman penceresi kullanır.

3. Kimlik doğrulama ve imza

Her istekte üç katman vardır:

İmza nasıl hesaplanır

imzalanan_metin = <unix_saniye> + "." + <istek gövdesinin ham baytları>
imza            = HMAC_SHA256(imzalanan_metin, api_secret)  →  64 haneli küçük harf hex

Gönderilecek başlıklar:

X-API-Key:           <api_key>
X-WinPay-Timestamp:  1789305600
X-WinPay-Signature:  3f2a9c...64 hane...b1
Content-Type:        application/json

Zaman penceresi ±300 saniyedir. Saatiniz 5 dakikadan fazla kayarsa istekler reddedilir.

⚠️ En sık yapılan hata: gövdeyi bir kez oluşturup aynı string'i hem imzalayın hem gönderin. JSON'u ayrıştırıp yeniden üretirseniz anahtar sırası değişebilir ve imza tutmaz. İmza gönderdiğiniz baytların üzerinden doğrulanır.

4. Yatırım

4.1 Talep

POST /api/v1/deposits/init

{
  "request_id": "dep-20260910-000001",
  "member_id": "uye-42",
  "member_name": "Ali Veli",
  "amount": "1000.00",
  "is_fast": false
}

Kabul edilmeyen tutarlar: "1.000,00", -100, 0, "1.001", 1e3, "abc" → 400.

Banka hesabını ve IBAN'ı siz seçmezsiniz; sistem tutara uygun hesabı belirler. Siteniz gövdeden değil, API anahtarından tanınır.

4.2 Yanıt — 201

{
  "success": true,
  "data": {
    "transaction_id": 201,
    "payment_url": "https://api.win-pay.co/pay/<64-hane-token>",
    "amount": "1000.00",
    "status": "pending_payment",
    "expires_at": "2026-09-10T17:00:00.000Z"
  }
}

4.3 Üyeyi yönlendirin

• Tokeni siz üretmeyin, yanıttan geleni kullanın.
• Üst seviye yönlendirme yapın (iframe içinde çalışacağını varsaymayın).
• Linki analytics, chat, referrer ve loglarda paylaşmayın — linki bilen sayfayı görür.

Süre: 20 dakika. Bu süre içinde onaylanmayan talep expired olur.

Tutar değişebilir. Üye ödeme sayfasında sizin gönderdiğinizden farklı bir tutar seçebilir. Bakiyeye yazacağınız tutar callback'teki approved_amount olmalıdır — ilk amount değil.

5. Çekim

POST /api/v1/withdrawals/init

{
  "request_id": "wd-20260910-000001",
  "member_id": "uye-42",
  "member_name": "Ali Veli",
  "amount": "500.00",
  "iban": "TR330006100519786457841326",
  "account_name": "ALI VELI"
}

Yatırımla aynı alanlar, is_fast yok, iki ek zorunlu alan var:

Yanıt — 201:

{
  "success": true,
  "data": {
    "transaction_id": 202,
    "status": "pending_assignment",
    "amount": "500.00"
  }
}

Çekimde payment_url dönmez. Sonucu callback ile alırsınız.

IBAN doğrulaması biçimi kontrol eder, hesabın kime ait olduğunu kanıtlamaz. Hesabın üyeye ait olduğunu doğrulamak ve çekilebilir bakiyeyi bloke etmek/iade etmek sizin tarafınızdadır.

6. Sonuç bildirimi (callback)

Entegrasyonun en kritik kısmı. Para burada kesinleşir.

6.1 Gelen istek

POST https://api.sitem.com/odeme/callback
Content-Type: application/json
X-WinPay-Signature: <64 haneli hex HMAC-SHA256>
X-WinPay-Event-Id: winpay:901

{
  "event_id": "winpay:901",
  "event": "transaction.approved",
  "transaction_id": 201,
  "request_id": "dep-20260910-000001",
  "type": "deposit",
  "amount": "1000.00",
  "approved_amount": "950.00",
  "status": "approved",
  "member_id": "uye-42",
  "timestamp": "2026-09-10T16:45:00.000Z"
}

Callback imzasında zaman damgası öneki yoktur (isteklerinizden farklı) ve api_secret değil callback_secret kullanılır: HMAC_SHA256(ham gövde, callback_secret).

6.2 Doğrulama — sırayla yapın

1. İmzayı ham gövde baytları üzerinden doğrulayın. JSON'u parse edip yeniden stringify etmeyin. Karşılaştırmayı sabit süreli yapın (crypto.timingSafeEqual, hash_equals, hmac.compare_digest).
2. Gövdedeki event_id ile X-WinPay-Event-Id başlığı aynı olmalı.
3. request_id sizin açtığınız, o üyeye ait bir talep olmalı.
4. event_id değerini UNIQUE indeksli bir kolona yazın. Zaten varsa 2xx dönüp durun, ikinci bir mali hareket oluşturmayın.
5. Bakiye değişikliğini aynı veritabanı transaction'ında uygulayın.
6. Commit ettikten sonra 2xx dönün. Gövde okunmaz.

6.3 Hangi durumda ne yapmalı

6.4 Teslimat davranışı

Tekrarlar saatler sonra gelebilir. Sırf zaman geçti diye geçerli bir bildirimi atmayın; mükerrer korumasını kalıcı event_id kaydıyla yapın, zaman penceresiyle değil.

7. Durum kodları

yatırım:  pending_payment  →  pending_approval  →  approved
                                               →  rejected
                           →  expired (20 dk)

çekim:    pending_assignment  →  assigned  →  processing  →  completed
                                                          →  rejected

Yalnızca approved (yatırım) ve completed (çekim) başarı demektir. Yatırım hiçbir zaman completed olmaz.

8. Tekrar eden istekler

Tekrar anahtarı: site + işlem türü + request_id

Zaman aşımı aldıysanız yeni bir request_id üretmeyin; aynı request_id ile tekrar gönderin — sorgu gibi davranır ve mevcut işlemi döner.

Idempotency-Key başlığını da kullanabilirsiniz; gövdedeki request_id ile aynı olmalıdır.

Tekrar yanıtında expires_at bulunmayabilir. Yatırım ve çekim referansları ayrı sayılır, yine de dep- / wd- gibi ayırt edici önekler kullanın.

9. Hata kodları

Tüm hatalar aynı biçimdedir. code ile dallanın, message ile değil — mesajlar Türkçe, insan içindir ve değişebilir.

{ "success": false, "code": "BAD_REQUEST", "message": "Açıklama" }

Sınırlı uçlarda RateLimit-* yanıt başlıkları gönderilir.

Gerçek hata yanıtları

10. İstek sınırları

Aşarsanız 429 alırsınız; üstel geri çekilme (exponential backoff) uygulayın.

11. Örnek istemci kodu

Node.js

const crypto = require('crypto');

async function winpayCall(path, payload) {
  const body = JSON.stringify(payload);              // BİR KEZ üret
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const signature = crypto
    .createHmac('sha256', process.env.WINPAY_API_SECRET)
    .update(timestamp).update('.').update(Buffer.from(body, 'utf8'))
    .digest('hex');

  const res = await fetch(process.env.WINPAY_BASE_URL + path, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.WINPAY_API_KEY,
      'X-WinPay-Timestamp': timestamp,
      'X-WinPay-Signature': signature,
    },
    body,                                            // AYNI string
  });
  return { status: res.status, data: await res.json() };
}

// Callback doğrulama (Express — ham gövde şart)
app.post('/odeme/callback',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const expected = crypto
      .createHmac('sha256', process.env.WINPAY_CALLBACK_SECRET)
      .update(req.body)                              // Buffer, parse edilmemiş
      .digest('hex');
    const got = req.get('X-WinPay-Signature') || '';
    if (got.length !== expected.length ||
        !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString('utf8'));
    if (event.event_id !== req.get('X-WinPay-Event-Id')) return res.sendStatus(400);

    await db.transaction(async (t) => {
      const [, created] = await t.findOrCreate({ where: { event_id: event.event_id } });
      if (!created) return;                          // zaten işlenmiş
      if (event.type === 'deposit' && event.status === 'approved') {
        await creditMember(t, event.member_id, event.approved_amount);
      }
    });
    res.sendStatus(200);
  });

PHP

<?php
function winpay_call(string $path, array $payload): array {
    $body      = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    $timestamp = (string) time();
    $signature = hash_hmac('sha256', $timestamp . '.' . $body, getenv('WINPAY_API_SECRET'));

    $ch = curl_init(getenv('WINPAY_BASE_URL') . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $body,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 20,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'X-API-Key: '          . getenv('WINPAY_API_KEY'),
            'X-WinPay-Timestamp: ' . $timestamp,
            'X-WinPay-Signature: ' . $signature,
        ],
    ]);
    $response = curl_exec($ch);
    $status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    return ['status' => $status, 'data' => json_decode($response, true)];
}

// Callback doğrulama
$raw      = file_get_contents('php://input');        // HAM gövde
$expected = hash_hmac('sha256', $raw, getenv('WINPAY_CALLBACK_SECRET'));
$got      = $_SERVER['HTTP_X_WINPAY_SIGNATURE'] ?? '';
if (!hash_equals($expected, $got)) { http_response_code(401); exit; }
$event = json_decode($raw, true);

Python

import hmac, hashlib, json, time, os, requests

def winpay_call(path, payload):
    body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
    timestamp = str(int(time.time()))
    signature = hmac.new(
        os.environ["WINPAY_API_SECRET"].encode(),
        f"{timestamp}.".encode() + body.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return requests.post(
        os.environ["WINPAY_BASE_URL"] + path,
        data=body.encode("utf-8"),
        headers={
            "Content-Type": "application/json",
            "X-API-Key": os.environ["WINPAY_API_KEY"],
            "X-WinPay-Timestamp": timestamp,
            "X-WinPay-Signature": signature,
        },
        timeout=20,
    )

# Callback doğrulama
def verify(raw_body: bytes, header_signature: str) -> bool:
    expected = hmac.new(
        os.environ["WINPAY_CALLBACK_SECRET"].encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header_signature)

12. Uygulamanızı çevrimdışı doğrulayın

Aşağıdakiler yalnızca test değerleridir, üretimde kullanılmaz. Gerçek erişim bilgileri verilmeden önce HMAC kodunuzu bunlarla sınayabilirsiniz.

api_key         = wp_test_key_0001
api_secret      = test_api_secret_do_not_use_in_production
callback_secret = test_callback_secret_do_not_use_in_production

İstek imzası — bu zaman damgası ve gövde tam olarak bu imzayı üretmelidir:

timestamp = 1789041098
body      = {"request_id":"dep-20260910-000001","member_id":"member-42","member_name":"Ali Veli","amount":"1000.00","is_fast":false}
signature = e55ffec5d4ea23e78d86048bbd2d778349dd69efa0ea8c5961857d4ee1bba4fe

Callback doğrulaması — bu gövde tam olarak bu imzayı üretmelidir:

body      = {"event_id":"winpay:1","event":"transaction.approved","transaction_id":1,"request_id":"dep-20260910-000001","type":"deposit","amount":"1000.00","approved_amount":"950.00","status":"approved","member_id":"member-42","timestamp":"2026-09-10T11:51:38.941Z"}
signature = 9b2182c5a8155721a85bb246497c9d6a3d70c2b2c431bae1ab0fafdb23bf9aa7

Gerçek erişim bilgileriyle duman testi:

API_SECRET='<api_secret>'
API_KEY='<api_key>'
BASE='https://api.win-pay.co'

BODY='{"request_id":"dep-test-0001","member_id":"member-42","member_name":"Ali Veli","amount":"1000.00"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" -r | cut -d' ' -f1)

curl -i -X POST "$BASE/api/v1/deposits/init" \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $API_KEY" \
  -H "X-WinPay-Timestamp: $TS" \
  -H "X-WinPay-Signature: $SIG" \
  --data-raw "$BODY"

Aynı request_id ile iki kez çalıştırın: ikinci çağrı aynı transaction_id ile "idempotent": true dönmelidir.

13. Canlıya çıkmadan önce kontrol listesi

Kimlik ve imza

• Yanlış api_key → 401
• İmzasız istek → 401
• Bozuk imza → 401
• Saati 10 dakika ileri alıp istek → 401
• İzin listesi dışı bir IP'den istek → 403

Talep

• Geçerli yatırım → 201 + payment_url
• Geçerli çekim → 201
• amount olarak -100, 0, 1.001, "1.000,00", abc → hepsi 400
• Geçersiz IBAN → 400

Tekrar

• Aynı request_id + aynı gövde → tek işlem, idempotent: true
• Aynı request_id + farklı tutar → 409

Callback

• İmzayı ham gövde ile doğruluyorsunuz
• Bozuk imzalı bildirimi reddediyorsunuz
• Aynı event_id iki kez gelince ikinci kez bakiye yazmıyorsunuz
• deposit/approved için approved_amount kullanıyorsunuz
• withdrawal/completed ikinci bir ödeme emri tetiklemiyor
• Bakiyeyi yazdıktan sonra 2xx dönüyorsunuz

Uçtan uca

• Yatırım: talep → ödeme sayfası → callback → bakiye
• Farklı tutar seçilen yatırım: approved_amount doğru işleniyor
• Süresi dolan yatırım: expired geliyor, bakiye değişmiyor
• Çekim: talep → completed → çekim kapanıyor

14. Sık yapılan hatalar

Destek

Sorun bildirirken şunları hazırlayın: request_id, isteğin tam zamanı (saat dilimiyle), aldığınız HTTP kodu ve code alanı, sunucunuzun çıkış IP'si.

Sır göndermeyin — api_key, api_secret veya callback_secret değerlerini mesaja, ekran görüntüsüne veya loga yazmayın.