PayFerrari Merchant API

Kimlik doğrulama

Her iş yerinin iki anahtarı vardır. İkisi de iş yeri paneli → API anahtarları sayfasındadır.

Sandbox iş yerlerinde anahtarlar pk_test_ / sk_test_ önekiyle başlar ve tüm yanıtlarda "sandbox": true döner.

Başlıklar

X-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-PayFerrari-Timestamp: 1760000000
X-Signature: 3q0b7cF0m6l3…Vt8=
Content-Type: application/json

Panelde IP kısıtlaması tanımlıysa yalnızca listedeki IPv4/IPv6 adreslerinden ve CIDR bloklarından gelen istekler kabul edilir; diğerleri 403 ip_denied alır.

İstek imzalama

Önerilen (zaman damgalı): İsteğe X-PayFerrari-Timestamp başlığını ekleyin ve imza dizgisini v2 etiketi, zaman damgası ve her alan yeni satır (\n) ile ayrılmış olacak şekilde oluşturun. Ayraç kullanımı dizgi belirsizliğini ortadan kaldırır; zaman damgası imzaya bağlandığı için yakalanan bir istek tekrar oynatılamaz.

message   = "v2\n" + timestamp + "\n" + alan1 + "\n" + alan2 + …
signature = Base64( HMAC-SHA256( secret_key, message ) )

• payment_amount kuruş cinsinden tam sayıdır ve dizgiye ondalıksız yazılır (50000).
• email küçük harfe çevrilmiş ve baştaki/sondaki boşlukları kırpılmış haliyle imzalanır; currency büyük harfle (TRY).
• Cüzdan doğrulamada wallet_id yalnızca rakamlarına indirgenmiş haliyle imzalanır ("97 15 29" → 971529).
• Diğer alanlar gövdede gönderdiğiniz değerle birebir aynı olmalıdır.

Anahtar yenileme

Secret key'in sızdığından şüpheleniyorsanız veya periyodik olarak değiştirmek istiyorsanız panelde API anahtarları → Secret key'i yenile adımını kullanın. İşlem hesap şifrenizle onaylanır; public key değişmez.

Bağlantı testi

GET/v1/ping

Public key'i ve IP kısıtlamasını doğrular. İmza gerekmez; askıdaki iş yerleri için de yanıt döner.

curl https://payferrari.com/v1/ping \
  -H "X-Public-Key: $PF_PUBLIC_KEY"

{
  "status": "success",
  "service": "payferrari",
  "merchant": "Demo Mağaza",
  "sandbox": false,
  "time": "2026-10-12T12:00:00.000Z"
}

Yatırım başlatma

POST/v1/payments/init

Oyuncu bakiyesine yükleme için tek kullanımlık ödeme oturumu açar. Oyuncuyu yanıttaki payment_url adresine yönlendirin. Oturum 15 dakika geçerlidir (sandbox: 10 dakika).

Gövde

{
  "merchant_oid": "DEP-10001",
  "payment_amount": 50000,
  "email": "oyuncu@site.com",
  "currency": "TRY",
  "merchant_ok_url": "https://siteniz.com/deposit/ok",
  "merchant_fail_url": "https://siteniz.com/deposit/fail",
  "merchant_notify_url": "https://siteniz.com/api/payferrari/notify",
  "user_basket": [{ "name": "Bakiye yükleme", "price": 50000, "qty": 1 }]
}

Yanıt

{
  "status": "success",
  "token": "W53_qCE6mXZ3WH2aWOqt1bzhF_4CeqfG",
  "payment_url": "https://payferrari.com/pay/W53_qCE6mXZ3WH2aWOqt1bzhF_4CeqfG",
  "expires_at": "2026-10-12T12:15:00.000Z",
  "sandbox": false
}

Siparişi yalnızca webhook status=success geldiğinde ve hash doğrulandıktan sonra “ödendi” işaretleyin. Dönüş URL'leri yalnızca kullanıcı deneyimi içindir.

İşlem durumu

POST/v1/payments/status

Yatırım veya çekim durumunu sorgular. Webhook gecikirse yedek kontrol olarak kullanın.

{ "merchant_oid": "DEP-10001" }

Yanıt

{
  "status": "success",
  "type": "deposit",
  "sandbox": false,
  "payment": {
    "merchant_oid": "DEP-10001",
    "status": "paid",
    "amount_kurus": 50000,
    "currency": "TRY",
    "paid_at": "2026-10-12T12:05:00.000Z",
    "notify_status": "delivered",
    "created_at": "2026-10-12T12:00:00.000Z",
    "expires_at": "2026-10-12T12:15:00.000Z"
  }
}

Çekimlerde type = withdraw ve payment.status = paid döner. Kayıt yoksa 404 not_found.

Cüzdan doğrulama

POST/v1/wallets/lookup

Çekimden önce üye numarası ile ad soyadın eşleştiğini kontrol edin.

{
  "wallet_id": "971529",
  "wallet_name": "Ege Yılmaz"
}

{ "status": "success", "wallet_no": "971529", "match": true, "sandbox": false }

match: ad gönderilmezse null; gönderilirse büyük/küçük harf ve Türkçe karakter farkları yok sayılarak karşılaştırılır.

Oyuncu çekimi

POST/v1/payouts

İş yeri bakiyenizden oyuncunun PayFerrari cüzdanına anında aktarım yapar. Ad soyad eşleşmesi zorunludur.

{
  "merchant_oid": "WD-90001",
  "payment_amount": 25000,
  "wallet_id": "971529",
  "wallet_name": "Ege Yılmaz",
  "merchant_notify_url": "https://siteniz.com/api/payferrari/notify"
}

{ "status": "success", "merchant_oid": "WD-90001", "wallet_no": "971529", "sandbox": false }

Aynı cüzdana bir saat içinde ikinci çekim gönderilemez (429 rate_limit). Bakiye yetersizse 400 balance döner.

Webhook'lar

İşlem sonuçlandığında PayFerrari, merchant_notify_url adresine POST application/json gönderir. Her teslimat X-PayFerrari-Signature ve X-PayFerrari-Timestamp başlıklarını taşır; imza, ham gövdenin zaman damgasına bağlı HMAC-SHA256 Base64 halidir. Yanıtınız HTTP 2xx olmalı ve gövdesinde OK geçmelidir.

X-PayFerrari-Timestamp: 1760000000
X-PayFerrari-Signature: Base64( HMAC-SHA256( secret_key, timestamp + "." + ham_gövde ) )
X-PayFerrari-Event: deposit

{
  "merchant_oid": "DEP-10001",
  "status": "success",
  "payment_amount": 50000,
  "currency": "TRY",
  "hash": "Base64(HMAC-SHA256(secret_key, merchant_oid + status + payment_amount))",
  "type": "deposit"
}

• Doğrulamayı X-PayFerrari-Signature başlığıyla yapın (önerilen); gövdedeki hash alanı geriye dönük uyumluluk içindir.
• Zaman damgası ±5 dakikadan eski ise bildirimi reddedin (tekrar koruması).
• type: yatırımda deposit, oyuncu çekiminde withdraw.
• metadata (isteğe bağlı): panelden oluşturduğunuz ödeme bağlantısına eklediğiniz ek bilgiler varsa anahtar/değer nesnesi olarak aynen iletilir.
• Zaman aşımı 2,5 saniyedir. Başarısız teslimatlar üstel artan aralıklarla (en fazla 5 dakikada bir) yeniden denenir.
• Aynı bildirim birden fazla gelebilir; merchant_oid bazında idempotent işleyin.
• Teslimat kayıtlarını, test gönderimini ve manuel yeniden denemeyi panelde Webhook'lar sayfasında bulabilirsiniz.

import crypto from "node:crypto";
import express from "express";

const SECRET_KEY = process.env.PF_SECRET_KEY;
const app = express();

// İmza ham gövde üzerinden doğrulanır: express.raw kullanın
app.post("/api/payferrari/notify", express.raw({ type: "*/*" }), (req, res) => {
  const ts = req.get("X-PayFerrari-Timestamp") || "";
  const sig = req.get("X-PayFerrari-Signature") || "";
  const raw = req.body; // Buffer
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(401).send("timestamp");
  const expected = crypto.createHmac("sha256", SECRET_KEY)
    .update(`${ts}.${raw}`).digest("base64");
  const a = Buffer.from(sig), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.status(401).send("sign");

  const { merchant_oid, status } = JSON.parse(raw.toString("utf8"));
  // merchant_oid için idempotent: daha önce işlendiyse yalnızca OK dönün
  res.type("text/plain").send("OK");
});

<?php
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_PAYFERRARI_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_PAYFERRARI_SIGNATURE'] ?? '';
$expected = base64_encode(hash_hmac('sha256', $ts . '.' . $raw, getenv('PF_SECRET_KEY'), true));
if (abs(time() - (int) $ts) > 300 || !hash_equals($expected, (string) $sig)) {
    http_response_code(401);
    exit('sign');
}
$p = json_decode($raw, true) ?: [];
// merchant_oid için idempotent işleyin
echo 'OK';

import base64, hashlib, hmac, os, time
from flask import Flask, abort, request

SECRET_KEY = os.environ["PF_SECRET_KEY"].encode()
app = Flask(__name__)

@app.post("/api/payferrari/notify")
def notify():
    raw = request.get_data()
    ts = request.headers.get("X-PayFerrari-Timestamp", "")
    sig = request.headers.get("X-PayFerrari-Signature", "")
    expected = base64.b64encode(hmac.new(SECRET_KEY, f"{ts}.".encode() + raw, hashlib.sha256).digest()).decode()
    if abs(time.time() - int(ts or 0)) > 300 or not hmac.compare_digest(expected, sig):
        abort(401)
    p = request.get_json(force=True)
    # merchant_oid için idempotent işleyin
    return "OK"

Tutarlar ve limitler

• Tüm tutarlar kuruş cinsindendir: 500,00 TL → 50000. Para birimi TRY.
• Minimum yatırım ve minimum çekim tutarları iş yerinize özeldir (panel → Güvenlik ve ayarlar → Hesap bilgileri).
• merchant_oid iş yeri içinde benzersizdir; tekrar gönderimde 409 duplicate_oid döner.
• IP başına dakikalık istek limitleri: init 120, status 180, lookup 60, payouts 80. Aşımda 429 rate_limit.

Hata kodları

Hatalı isteklerde gövde { "status": "failed", "reason": "…" } biçimindedir; bazı hatalarda açıklayıcı bir message alanı da bulunur.

Örnek kod

Anahtarları PF_PUBLIC_KEY ve PF_SECRET_KEY ortam değişkenlerinde saklayın. Örnek, yatırım oturumu açar.

import crypto from "node:crypto";

const PUBLIC_KEY = process.env.PF_PUBLIC_KEY; // pk_live_…
const SECRET_KEY = process.env.PF_SECRET_KEY; // sk_live_… yalnızca sunucuda
const sign = (ts, ...fields) =>
  crypto.createHmac("sha256", SECRET_KEY).update(["v2", ts, ...fields].join("\n")).digest("base64");

const order = {
  merchant_oid: `DEP-${Date.now()}`,
  payment_amount: 50000, // 500,00 TL
  email: "oyuncu@site.com",
  currency: "TRY",
  merchant_ok_url: "https://siteniz.com/deposit/ok",
  merchant_fail_url: "https://siteniz.com/deposit/fail",
  merchant_notify_url: "https://siteniz.com/api/payferrari/notify",
};

const ts = Math.floor(Date.now() / 1000);
const res = await fetch("https://payferrari.com/v1/payments/init", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Public-Key": PUBLIC_KEY,
    "X-PayFerrari-Timestamp": String(ts),
    "X-Signature": sign(ts, PUBLIC_KEY, order.merchant_oid, order.payment_amount, order.email,
      order.currency, order.merchant_ok_url, order.merchant_fail_url),
  },
  body: JSON.stringify(order),
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.reason);
// Oyuncuyu data.payment_url adresine yönlendirin

<?php
$publicKey = getenv('PF_PUBLIC_KEY');
$secretKey = getenv('PF_SECRET_KEY');

$order = [
    'merchant_oid'        => 'DEP-' . time(),
    'payment_amount'      => 50000,
    'email'               => 'oyuncu@site.com',
    'currency'            => 'TRY',
    'merchant_ok_url'     => 'https://siteniz.com/deposit/ok',
    'merchant_fail_url'   => 'https://siteniz.com/deposit/fail',
    'merchant_notify_url' => 'https://siteniz.com/api/payferrari/notify',
];
$ts = time();
$raw = "v2\n" . $ts . "\n" . implode("\n", [
    $publicKey, $order['merchant_oid'], $order['payment_amount'], $order['email'],
    $order['currency'], $order['merchant_ok_url'], $order['merchant_fail_url'],
]);
$signature = base64_encode(hash_hmac('sha256', $raw, $secretKey, true));

$ch = curl_init('https://payferrari.com/v1/payments/init');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Public-Key: ' . $publicKey,
        'X-PayFerrari-Timestamp: ' . $ts,
        'X-Signature: ' . $signature,
    ],
    CURLOPT_POSTFIELDS     => json_encode($order),
]);
$data = json_decode(curl_exec($ch), true);
// header('Location: ' . $data['payment_url']);

import base64, hashlib, hmac, json, os, time, urllib.request

PUBLIC_KEY = os.environ["PF_PUBLIC_KEY"]
SECRET_KEY = os.environ["PF_SECRET_KEY"]

def sign(ts, *fields):
    raw = "\n".join(["v2", str(ts), *[str(f) for f in fields]]).encode()
    return base64.b64encode(hmac.new(SECRET_KEY.encode(), raw, hashlib.sha256).digest()).decode()

order = {
    "merchant_oid": f"DEP-{int(time.time())}",
    "payment_amount": 50000,
    "email": "oyuncu@site.com",
    "currency": "TRY",
    "merchant_ok_url": "https://siteniz.com/deposit/ok",
    "merchant_fail_url": "https://siteniz.com/deposit/fail",
    "merchant_notify_url": "https://siteniz.com/api/payferrari/notify",
}
ts = int(time.time())
signature = sign(ts, PUBLIC_KEY, order["merchant_oid"], order["payment_amount"], order["email"],
                 order["currency"], order["merchant_ok_url"], order["merchant_fail_url"])
req = urllib.request.Request(
    "https://payferrari.com/v1/payments/init",
    data=json.dumps(order).encode(), method="POST",
    headers={"Content-Type": "application/json", "X-Public-Key": PUBLIC_KEY,
             "X-PayFerrari-Timestamp": str(ts), "X-Signature": signature},
)
data = json.loads(urllib.request.urlopen(req).read())
# Oyuncuyu data["payment_url"] adresine yönlendirin

OID="DEP-$(date +%s)"
AMOUNT=50000
EMAIL="oyuncu@site.com"
OK="https://siteniz.com/deposit/ok"
FAIL="https://siteniz.com/deposit/fail"
TS=$(date +%s)
SIG=$(printf 'v2\n%s\n%s\n%s\n%s\n%s\nTRY\n%s\n%s' "$TS" "$PF_PUBLIC_KEY" "$OID" "$AMOUNT" "$EMAIL" "$OK" "$FAIL" \
  | openssl dgst -sha256 -hmac "$PF_SECRET_KEY" -binary | base64)

curl https://payferrari.com/v1/payments/init \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: $PF_PUBLIC_KEY" \
  -H "X-PayFerrari-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d "{\"merchant_oid\":\"$OID\",\"payment_amount\":$AMOUNT,\"email\":\"$EMAIL\",\"currency\":\"TRY\",
       \"merchant_ok_url\":\"$OK\",\"merchant_fail_url\":\"$FAIL\",
       \"merchant_notify_url\":\"https://siteniz.com/api/payferrari/notify\"}"

Canlıya geçiş

1. Panelde API anahtarları sayfasından public key'i kopyalayın; secret key'i şifrenizle görüntüleyip sunucu ortam değişkenine kaydedin.
2. GET /v1/ping ile public key'i ve IP kısıtlamasını doğrulayın.
3. Bildirim adresinizi HTTPS olarak kaydedin ve panelden test webhook'u gönderin.
4. Üretim sunucusu IP'lerinizi panelde IP kısıtlamasına ekleyin.
5. Yatırım: init → yönlendirme → webhook hash doğrulama → bakiye yükleme (merchant_ok_url yalnızca kullanıcı deneyimi içindir).
6. Çekim: lookup (match=true) → payouts → webhook → site bakiyesinden düşme.
7. merchant_oid değerlerini kendi tarafınızda benzersiz ve idempotent saklayın.
8. Secret key'i düzenli olarak geçiş süreli yenileyin.

Destek: iş yeri paneli · kurumsal