Süper Pay

API Dokümantasyonu

Genel Bakış

Süper Pay API

Süper Pay API'ı; müşterilerin para yatırma, para çekme ve işlem durumu sorgulama işlemlerini güvenli bir şekilde gerçekleştirmesine olanak tanır. Tüm istekler HTTPS üzerinden ve hash imzasıyla doğrulanır.

API Base URLhttps://superfinancepay.com
Dokümantasyonhttps://doc.superfinancepay.com
Tüm API çağrılarını her zaman HTTPS üzerinden yapın. Yatırım endpoint'i tarayıcı yönlendirmesiyle (GET, query string) çalışır; çekim ve durum sorgulama POST endpoint'lerinde istek ve yanıt gövdesi JSON formatındadır.

Kimlik Doğrulama

Kimlik Bilgileri

Her müşteriye aşağıdaki bilgiler verilir. Bu bilgileri gizli tutun ve kimseyle paylaşmayın.

ParametreTipZorunluAçıklama
Terminal IDStringEvetMüşteri tanımlayıcınız (örn: demobahis)
API KeyStringEvetİşlemleri imzalamak için kullanılan anahtar (pk_live_...)
Secret KeyStringEvetHash hesaplamasında kullanılan gizli anahtar (sk_live_...)
örnek kimlik
Terminal ID: demobahis
API Key:     pk_live_a1b2c3d4e5f6g7h8i9j0
Secret Key:  sk_live_z9y8x7w6v5u4t3s2r1q0
Secret Key’i asla paylaşmayın. Secret Key yalnızca kendi sunucunuzda kalmalı, istemci tarafına (tarayıcı, mobil uygulama) gönderilmemelidir.

Başlangıç

Kurulum ve Entegrasyon

Entegrasyon iki taraflı bir bilgi alışverişiyle başlar: Süper Pay size erişim bilgilerinizi verir, siz de karşılığında oyuncu yönlendirmesi ve bildirimler için iki adres iletirsiniz.

Süper Pay’in Size Verdikleri

Hesabınız açıldığında size özel Terminal ID, API Key ve Secret Key tanımlanır (bkz. Kimlik Bilgileri). Tüm istekleriniz bu bilgilerle imzalanır ve doğrulanır.

Sizin Süper Pay’e İletmeniz Gerekenler

BilgiAmaçKaynak
Affiliate (yönlendirme) linkiOyuncu, deposit sayfasındaki işlemini tamamladıktan sonra bu adres üzerinden sitenize geri döner.Entegrasyon sonrası bizzat sizden talep edilir.
Callback adresiİşlem talepleri sonuçlandığında (onay/iptal) sonuç bildiriminin gönderileceği adres.Sitenizi satın aldığınız yazılım firması tarafından sağlanır.
Affiliate linki yalnızca oyuncunun ödeme sonrası sitenize dönüşü içindir; işlem başına gönderdiğiniz redirecturl parametresinden bağımsız, hesabınıza kayıtlı genel yönlendirme adresidir. Callback adresini genellikle site yazılımınızı sağlayan firma verir; bu adrese gönderilen bildirimlerin nasıl işleneceği Callback (Webhook) bölümünde anlatılmıştır.

Güvenlik

Hash Hesaplama

Hash, isteğinizin gerçekten size ait olduğunu ispatlayan SHA-256 imzasıdır. Parametreler tam sırayla ve aralarında boşluk olmadan birleştirilir, ardından SHA-256 ile 64 karakterlik hex özet üretilir.

İşlemHash Formülü
YatırımapiKey + islemid + tuser + tadsoyad + amount + secretKey
ÇekimapiKey + islemid + tuser + tadsoyad + amount + secretKey
Durum SorgulamaapiKey + islemid + secretKey
Parametre sırası ve boşluksuz birleştirme kritiktir. Sıra hatalıysa veya araya boşluk eklenirse hash geçersiz olur ve istek reddedilir.

Tutar (amount) Formatı

amount her zaman ondalık ayracı nokta olacak şekilde gönderilmelidir. Hash, tutar tam olarak gönderdiğiniz metinle hesaplanır; bu yüzden hash’te kullandığınız değer ile istekte gönderdiğiniz değer birebir aynı olmalıdır.

DoğruYanlış
1000.001.000,00 · 1000,00

Endpoint

Yatırım

Yatırım talebini başlatmak için oyuncuyu aşağıdaki URL’ye yönlendirin (tarayıcıda açın). Oyuncu bu sayfada ödeme yöntemini onaylayıp talebini oluşturur. Tüm parametreler query string ile gönderilir ve zorunludur.

GET/deposit/{terminalid}?tuser={tuser}&tadsoyad={tadsoyad}&amount={amount}&islemid={islemid}&payment_name={payment_name}&hash={hash}&redirecturl={redirecturl}
ParametreTipZorunluAçıklama
terminalidString (path)EvetTerminal ID (örn: demobahis)
tuserString (query)EvetSistem kullanıcı adı
tadsoyadString (query)EvetAd Soyad (gerçek isim)
amountString (query)EvetYatırım tutarı TRY (örn: "1000.00")
islemidString (query)EvetBenzersiz işlem ID
payment_nameString (query)EvetÖdeme yöntemi (aşağıdaki listeden)
hashString (query)EvetSHA256 imzası (aşağıdaki formül)
redirecturlString (query)Evetİşlem sonrası oyuncunun döneceği URL

Hash Formülü

hash
SHA256(apiKey + islemid + tuser + tadsoyad + amount + secretKey)

Desteklenen Ödeme Yöntemleri

Banka

havale1 · havale2 · havale3 · havale4 · viphavale1 · viphavale2 · papara

Kripto

bitcoin · tethertrc20 · tethererc20 · tron · solana

Örnek

Örnek
https://superfinancepay.com/deposit/demobahis?tuser=user123&tadsoyad=Ahmet%20Yilmaz&amount=1000.00&islemid=TRX20260325001&payment_name=havale1&hash=SHA256_DEGERI&redirecturl=https%3A%2F%2Fsiteniz.com%2Fgeri-donus

Akış

Bu endpoint bir JSON yanıtı döndürmez. Oyuncu, ödeme yöntemini onayladığı yatırım sayfasına yönlendirilir; talep oluşturulduktan sonra redirecturl adresine geri döner. İşlemin nihai durumunu öğrenmek için Durum Sorgulama endpoint’ini veya callback’i kullanın.

Parametrelerden herhangi biri eksikse ya da hash geçersizse yatırım sayfası açılmaz ve oyuncuya hata gösterilir.
URL encode zorunlu: Tüm query parametreleri, özellikle redirecturl ve boşluk içeren tadsoyad, mutlaka URL encode edilmelidir. Aksi halde redirecturl kendi query parametrelerini içeriyorsa (örn. ?user=123&source=pay) URL bozulur. JavaScript’te URLSearchParams veya PHP’de urlencode() bunu otomatik yapar.
Kripto not: Kripto ödemelerinde gösterilen tutar canlı kur üzerinden hesaplanır.

Endpoint

Çekim

Çekim talebi POST yöntemiyle, sunucudan sunucuya (server-to-server) gönderilir. İstek gövdesi JSON’dır ve hash imzası zorunludur.

POST/api/withdraw

İstek Gövdesi

ParametreTipZorunluAçıklama
terminalidStringEvetTerminal ID
tuserStringEvetSistem kullanıcı adı
tadsoyadStringEvetAd Soyad (gerçek isim)
amountStringEvetÇekim tutarı (örn: "500.00")
islemidStringEvetBenzersiz çekim ID (maks. 100 karakter)
payment_nameStringEvetÖdeme yöntemi slug (Yatırım bölümündeki liste geçerlidir)
cekim_ibanStringEvetFiat yöntemlerde paranın transfer edileceği IBAN; kripto yöntemlerde ise cüzdan (wallet) adresi olarak kullanılır
hashString (64)EvetSHA256 imzası
payment_name için Yatırım bölümündeki ödeme yöntemi slug’ları geçerlidir (örn. havale1, papara, viphavale1 veya kripto yöntemleri). Çekim için ayrı bir liste yoktur; aynı slug’ları kullanın.

Hash Formülü

hash
SHA256(apiKey + islemid + tuser + tadsoyad + amount + secretKey)

Yanıtlar

201 · oluşturuldu
{
  "message": "İşlem başarıyla oluşturuldu",
  "islemid": "CKM20260325001",
  "redirect_url": null,
  "status": "pending"
}
redirect_url yalnızca yatırım işlemlerinde dolu döner. Çekim server-to-server olduğu ve bir yönlendirme akışı bulunmadığı için çekim cevabında her zaman null döner.
islemid, çekimde gönderdiğiniz benzersiz işlem ID’nizin aynısıdır; durum sorgulamasını da bu değerle yaparsınız. Çekim her zaman pending olarak başlar; talep sonuçlandığında sonuç, sistemde kayıtlı callback URL’inize otomatik olarak gönderilir (aşağıdaki Callback bölümüne bakın).
409 · duplicate islemid
{ "error": "Bu işlem ID'si ile daha önce bir işlem yapılmış." }
400 · eksik alan
{ "error": "Eksik zorunlu alanlar" }

Endpoint

Durum Sorgulama (POST)

İşlem durumunu hash ile güvenli şekilde sorgulamak için POST yöntemini kullanın.

POST/api/status-check

İstek Gövdesi

request · json
{
  "terminalid": "demobahis",
  "islemid": "TRX20260325001",
  "hash": "sha256_hash_degeri"
}

Hash

Ayrıca bir hash hesaplamanıza gerek yoktur. Sorgulamak istediğiniz işlemin, işlemi oluştururken gönderdiğiniz hash bilgisini göndermeniz yeterlidir.

Yanıtlar

200 · başarılı
{
  "terminalid": "demobahis",
  "tuser": "user123",
  "tadsoyad": "Ahmet Yilmaz",
  "amount": "1000.00",
  "islemid": "TRX20260325001",
  "payment_name": "bitcoin",
  "status": "pending",
  "type": "deposit",
  "cekim_iban": null,
  "redirecturl": "https://siteniz.com/geri-donus",
  "hash": "sha256_hash_degeri"
}
cekim_iban yalnızca çekim işlemlerinde dolu gelir; yatırımlarda null döner. Bu endpoint yan etkisizdir: yalnızca işlem durumunu döndürür, callback tetiklemez. Durumu istediğiniz sıklıkta güvenle sorgulayabilirsiniz; callback yalnızca işlem durumu değiştiğinde otomatik gönderilir.
401 · geçersiz hash
{ "error": "Invalid hash - unauthorized" }
404 · işlem bulunamadı
{ "error": "Transaction not found" }

Status Değerleri

StatusTürAçıklama
pendingAra durumİşlem bekliyor. Tekrar sorgulanabilir; henüz nihai değildir.
completedFinalİşlem onaylandı ve başarıyla tamamlandı.
canceledFinalİşlem iptal edildi / reddedildi.
Yalnızca pending ara durumdur ve tekrar sorgulanabilir. completed ve canceled nihai (final) durumlardır; değişmezler ve tekrar sorgulamaya gerek yoktur.

Bildirim

Callback (Webhook)

Callback yalnızca bir işlemin durumu değiştiğinde — yani pending iken completed ya da canceled olduğunda — kayıtlı callback URL’inize otomatik olarak bir POST isteği olarak gönderilir. Böylece işlemi sürekli sorgulamanıza gerek kalmaz. Durum sorgulama (status-check) endpoint’i callback tetiklemez. Callback URL’iniz size özel olarak tanımlanır.

POST{sizin_callback_url_iniz}

Callback Gövdesi

callback · json
{
  "tuser": "user123",
  "tadsoyad": "Ahmet Yilmaz",
  "amount": "1000.00",
  "islemid": "TRX20260325001",
  "hash": "sha256_hash_degeri",
  "updated_at": "2026-03-25T10:30:45.000000Z",
  "type": "deposit",
  "status": "completed",
  "status_reason": ""
}
ParametreTipZorunluAçıklama
tuserStringEvetİşlemi başlatırken gönderdiğiniz kullanıcı ID’si
tadsoyadStringEvetİşlemi başlatırken gönderdiğiniz ad soyad
amountStringEvetİşlem tutarı (ondalık, örn. "1000.00")
islemidStringEvetİşleminizin benzersiz ID’si; gönderdiğinizin aynısıdır
hashStringEvetOrijinal istekte gönderdiğiniz hash ile aynıdır
updated_atString (ISO 8601)Evetİşlem durumunun güncellendiği zaman damgası
typeStringEvetİşlem türü: "deposit" veya "withdrawal"
statusStringEvetNihai durum: completed veya canceled
status_reasonStringHayırİptal açıklaması (varsa, yoksa boş string)

Callback Hash Doğrulama

Callback’in gerçekten Süper Pay’den geldiğini doğrulamak için hash alanını kontrol edin. Sistem callback için yeni bir hash üretmez; callback’te gelen hash, o işlemi başlatırken (yatırım/çekim) sizin gönderdiğiniz hash’in birebir aynısıdır.

Doğrulamak için, işlem başlarken islemid ile birlikte kaydettiğiniz hash değeri ile callback’te gelen hash’i karşılaştırın. İsterseniz aynı formülle yeniden hesaplayıp da doğrulayabilirsiniz:

callback hash = işlem hash
SHA256(apiKey + islemid + tuser + tadsoyad + amount + secretKey)

Sizden Beklenen Yanıt

Callback’i başarıyla aldığınızı bildirmek için gövdesinde status alanı success (veya true) olan bir JSON dönmelisiniz. Yanıt mutlaka Content-Type: application/json başlığıyla gönderilmelidir. OK gibi düz metin bir yanıt JSON olarak ayrıştırılamaz ve başarısız onay sayılır; bu da callback’in tekrar denenmesine yol açar.

beklenen yanıt · json
{ "status": "success" }
Tekrar deneme: Başarılı yanıt alınamazsa callback 5 saniye arayla 3 kez tekrar denenir. Bu yüzden callback ucunuz idempotent olmalı (aynı islemid’yi birden çok kez alabilirsiniz). Not: Tekrar denemelerin başarısız olması işlemin durumunu değiştirmez; işlem yine completed veya canceled olarak kalır.

Güvenlik

IP Whitelist

Sunucularınızda IP kısıtlaması uyguluyorsanız, Süper Pay tarafından gönderilen isteklerin (özellikle callback / webhook bildirimlerinin) engellenmemesi için aşağıdaki IP adreslerimizi güvenli listenize (whitelist) eklemeniz gerekir.

Süper Pay IP Adresleri

54.195.3.54
54.217.142.99
52.28.237.66
18.184.145.190
3.11.47.11
18.135.114.51
35.181.64.132
35.181.116.200
Bu IP adresleri Süper Pay altyapısına aittir ve callback isteklerimiz bu adreslerden gönderilir. Tümünü whitelist’e eklediğinizden emin olun; aksi halde bazı bildirimler ulaşmayabilir.

Referans

Hata Kodları

KodAnlamıAçıklama
200OKİşlem başarılı
201CreatedYeni kayıt oluşturuldu
400Bad RequestEksik veya yanlış parametreler
401UnauthorizedYetkisiz (hash hatası)
404Not Foundİşlem bulunamadı
409ConflictDuplicate işlem ID
500Server ErrorSunucu hatası
hata formatı · json
{
  "error": "Hata açıklaması",
  "details": "Opsiyonel detay bilgisi"
}

Sık Karşılaşılan Hatalar

HTTPerror mesajıSebep
400Missing required fields / Eksik zorunlu alanlarZorunlu bir alan gönderilmedi
401Hash validation failedYatırım/çekim hash imzası hatalı
401Invalid hash - unauthorizedDurum sorgulamada hash eşleşmedi
404Customer not found / Geçersiz terminal IDTerminal ID sistemde yok
404Transaction not foundİşlem (islemid) bulunamadı
409Duplicate transaction IDAynı islemid ile daha önce işlem yapılmış

Entegrasyon

Kod Örnekleri

Yatırım URL’i Oluşturma — Node.js

javascript
const crypto = require('crypto')

const apiKey = 'pk_live_abc123'
const secretKey = 'sk_live_xyz789'
const terminalid = 'demobahis'

const tuser = 'user123'
const tadsoyad = 'Ahmet Yilmaz'
const amount = '1000.00'
const islemid = 'TRX20260325001'
const payment_name = 'havale1'
const redirecturl = 'https://siteniz.com/geri-donus'

// Yatırım hash: apiKey + islemid + tuser + tadsoyad + amount + secretKey
const hash = crypto
  .createHash('sha256')
  .update(apiKey + islemid + tuser + tadsoyad + amount + secretKey)
  .digest('hex')

const params = new URLSearchParams({
  tuser, tadsoyad, amount, islemid, payment_name, hash, redirecturl,
})

// Oyuncuyu bu URL'ye yönlendirin:
const depositUrl = `https://superfinancepay.com/deposit/${terminalid}?${params.toString()}`
console.log(depositUrl)

Çekim — Node.js

javascript
const crypto = require('crypto')

const apiKey = 'pk_live_abc123'
const secretKey = 'sk_live_xyz789'
const terminalid = 'demobahis'

const tuser = 'user123'
const tadsoyad = 'Ahmet Yilmaz'
const amount = '500.00'
const islemid = 'CKM20260325001'
const payment_name = 'havale1'
const cekim_iban = 'TR123456789012345678901234'

const hashString = apiKey + islemid + tuser + tadsoyad + amount + secretKey
const hash = crypto.createHash('sha256').update(hashString).digest('hex')

const res = await fetch('https://superfinancepay.com/api/withdraw', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    terminalid, tuser, tadsoyad, amount,
    islemid, payment_name, cekim_iban, hash,
  }),
})
console.log(await res.json())

Çekim — Python

python
import hashlib, requests

api_key = 'pk_live_abc123'
secret_key = 'sk_live_xyz789'

tuser = 'user123'
tadsoyad = 'Ahmet Yilmaz'
amount = '500.00'
islemid = 'CKM20260325001'

hash_string = api_key + islemid + tuser + tadsoyad + amount + secret_key
hash_value = hashlib.sha256(hash_string.encode()).hexdigest()

res = requests.post('https://superfinancepay.com/api/withdraw', json={
    'terminalid': 'demobahis',
    'tuser': tuser,
    'tadsoyad': tadsoyad,
    'amount': amount,
    'islemid': islemid,
    'payment_name': 'havale1',
    'cekim_iban': 'TR123456789012345678901234',
    'hash': hash_value,
})
print(res.json())

Çekim — PHP

php
<?php
$apiKey = 'pk_live_abc123';
$secretKey = 'sk_live_xyz789';

$tuser = 'user123';
$tadsoyad = 'Ahmet Yilmaz';
$amount = '500.00';
$islemid = 'CKM20260325001';

$hashString = $apiKey . $islemid . $tuser . $tadsoyad . $amount . $secretKey;
$hash = hash('sha256', $hashString);

$data = [
  'terminalid' => 'demobahis',
  'tuser' => $tuser,
  'tadsoyad' => $tadsoyad,
  'amount' => $amount,
  'islemid' => $islemid,
  'payment_name' => 'havale1',
  'cekim_iban' => 'TR123456789012345678901234',
  'hash' => $hash,
];

$ch = curl_init('https://superfinancepay.com/api/withdraw');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
echo curl_exec($ch);

Durum Sorgulama — Node.js

javascript
const crypto = require('crypto')

const apiKey = 'pk_live_abc123'
const secretKey = 'sk_live_xyz789'
const islemid = 'TRX20260325001'

const hash = crypto
  .createHash('sha256')
  .update(apiKey + islemid + secretKey)
  .digest('hex')

const res = await fetch('https://superfinancepay.com/api/status-check', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ terminalid: 'demobahis', islemid, hash }),
})
console.log(await res.json())