API Dokümantasyonu

Paybank Merchant API — havale/EFT ile yatırım (para yatırma) ve çekim (para çekme) işlemlerini sitenize entegre etmek için tek sayfa referans. Tüm uçlar JSON kabul eder ve JSON döner.

Genel bakış

• Base URL: https://mypybnk.com/api/ — her uç hem /api/{ad}.php hem de /api/v1/{ad} yolundan erişilebilir (ikisi aynı).
• Yöntem: yalnızca POST. Gövde application/json (önerilen) veya application/x-www-form-urlencoded.
• Karakter seti: UTF-8. Tutarlar TL cinsinden sayı (1250.50), binlik ayırıcı yok.
• Zaman: tüm tarih alanları sunucu saatiyle YYYY-MM-DD HH:MM:SS.
• Akış: create_payment → müşteri havale yapar → onay → sitenize callback gider. İsterseniz check_payment ile de sorgularsınız.

Kimlik doğrulama

Her istekte iki alan bulunur:

İsteğe bağlı olarak hesabınıza IP beyaz listesi tanımlanabilir; bu durumda yalnızca listedeki IP'lerden gelen istekler kabul edilir (401 — IP adresi izinli değil).

İmza (signature)

İmza, signature alanı hariç gönderdiğiniz JSON gövdesinin api_secret ile HMAC-SHA256 özeti, hex (küçük harf) olarak:

signature = HMAC_SHA256( json_encode(payload_without_signature), api_secret )

// PHP
$payload = [
  'api_key'       => $apiKey,
  'amount'        => 1250.50,
  'customer_name' => 'Ahmet Yılmaz',
  'order_id'      => 'SIP-10045',
];
$json = json_encode($payload,
  JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$payload['signature'] = hash_hmac('sha256', $json, $apiSecret);

$ch = curl_init('https://mypybnk.com/api/create_payment.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode($payload,
    JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
  CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);

// Node.js
const crypto = require('crypto');
const payload = {
  api_key: API_KEY,
  amount: 1250.5,
  customer_name: 'Ahmet Yılmaz',
  order_id: 'SIP-10045',
};
const json = JSON.stringify(payload);
payload.signature = crypto
  .createHmac('sha256', API_SECRET)
  .update(json).digest('hex');

const r = await fetch('https://mypybnk.com/api/create_payment.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
const data = await r.json();

Hesabınız için özel bir formül tanımlandıysa (ör. sha256({amount}{order_id}{secret})) size ayrıca bildirilir.

Yanıt formatı & hatalar

Başarılı yanıtlarda "success": true ve veri alanları; hatalarda "success": false ve "error" mesajı döner. HTTP durum kodu da anlamlıdır:

{ "success": false, "error": "Geçersiz imza" }
{ "success": false, "error": "Bu müşteri adı ile yatırım talebi oluşturulamaz", "code": "customer_blacklisted" }

create_payment — yatırım talebi oluştur

Müşteri için ödeme talebi açar; yanıtta havale yapılacak banka/IBAN ve müşteriye gösterebileceğiniz hazır payment_url döner. Talep, expires_at süresine kadar beklemede kalır; süre dolarsa otomatik reddedilir ve callback gider.

İstek

Yanıt

{
  "success": true,
  "payment_id": "PAY-261016-32F00F60",
  "amount": 1250.5,
  "bank_name": "Garanti BBVA",
  "account_holder": "A*** Y***",
  "iban": "TR330006200000012345678901",
  "payment_url": "https://mypybnk.com/payment/index.php?id=PAY-261016-32F00F60",
  "created_at": "2026-10-16 20:41:55",
  "expires_at": "2026-10-16 20:56:55",
  "timeout_minutes": 15,
  "customer_name": "Ahmet Yılmaz",
  "status": "pending",
  "provider": "internal",
  "provider_txid": null
}

check_payment — yatırım durumu sorgula

payment_status adıyla da erişilebilir (aynı uç).

{
  "success": true,
  "payment_id": "PAY-261016-32F00F60",
  "order_id": "SIP-10045",
  "amount": 1250.5,
  "approved_amount": 1250.5,
  "net_amount": 1188.0,
  "commission": 62.5,
  "customer_name": "Ahmet Yılmaz",
  "status": "approved",
  "created_at": "2026-10-16 20:41:55",
  "approved_at": "2026-10-16 20:43:10",
  "expires_at": "2026-10-16 20:56:55",
  "bank_name": "Garanti BBVA",
  "iban": "TR330006200000012345678901",
  "account_holder": "A*** Y***",
  "payment_url": "https://mypybnk.com/payment/index.php?id=PAY-261016-32F00F60",
  "reject_reason": null
}

approved_amount talep edilen tutardan farklı olabilir (müşteri eksik/fazla gönderdiyse). Bakiyeyi her zaman approved_amount üzerinden işleyin.

check_pending — bekleyen yatırımlar

Hesabınıza ait, hâlâ pending durumdaki talepleri (en fazla 200) listeler. Mutabakat/temizlik için kullanışlıdır.

{ "success": true, "count": 2, "payments": [ { "payment_id": "...", "status": "pending", ... } ] }

create_withdrawal — çekim talebi oluştur

Müşterinin IBAN'ına ödeme talebi açar. Ödeme ekibi işlemi tamamlayınca approved, yapılamazsa rejected callback'i gider.

{
  "success": true,
  "withdrawal_id": "WD-261016-7A1C22F0",
  "amount": 450.0,
  "customer_name": "Ahmet Yılmaz",
  "customer_iban": "TR330006200000012345678901",
  "status": "pending",
  "message": "Çekim talebi oluşturuldu"
}

check_withdrawal — çekim durumu sorgula

{
  "success": true,
  "withdrawal_id": "WD-261016-7A1C22F0",
  "order_id": "CEK-551",
  "amount": 450.0,
  "customer_name": "Ahmet Yılmaz",
  "customer_iban": "TR330006200000012345678901",
  "customer_bank": "Garanti BBVA",
  "status": "approved",
  "created_at": "2026-10-16 21:02:11",
  "completed_at": "2026-10-16 21:09:40",
  "reject_reason": null
}

reject_withdrawal — çekimi iptal et

Yalnızca henüz işleme alınmamış (pending) çekimler iptal edilebilir. İşleme alınmış/tamamlanmış çekimler için 400 döner ve mevcut durum bildirilir.

{ "success": true, "withdrawal_id": "WD-261016-7A1C22F0", "status": "rejected" }

Callback (webhook)

Bir yatırım veya çekimin durumu kesinleştiğinde panelde tanımlı callback URL'nize POST JSON gönderilir. Çekimler için ayrı bir URL tanımlıysa o kullanılır. Yanıtınız 2xx değilse artan aralıklarla tekrar denenir; bu yüzden aynı bildirimi birden fazla kez alabilirsiniz — payment_id/withdrawal_id ile tekilleştirin.

HTTP başlıkları

Yatırım bildirimi

{
  "type": "deposit",
  "payment_id": "PAY-261016-32F00F60",
  "order_id": "SIP-10045",
  "amount": 1250.5,
  "approved_amount": 1250.5,
  "net_amount": 1188.0,
  "commission": 62.5,
  "currency": "TRY",
  "status": "approved",
  "timestamp": 1760640190,
  "signature": "3f1c…",
  "hash": "9a7e…"
}

Çekim bildirimi

{
  "type": "withdrawal",
  "withdrawal_id": "WD-261016-7A1C22F0",
  "order_id": "CEK-551",
  "amount": 450.0,
  "currency": "TRY",
  "status": "approved",
  "completed_at": "2026-10-16 21:09:40",
  "timestamp": 1760640580,
  "signature": "b21d…",
  "hash": "c0a4…"
}

status rejected ise ek olarak "reason" alanı gelir (ör. Ödeme gelmedi, Süre doldu, IBAN hatalı). Bir işlem yönetim tarafından sonradan Onay → Red veya Red → Onay yapılırsa yeni durum için tekrar callback gönderilir; bakiyeyi son gelen duruma göre düzeltin.

Callback doğrulama

Gelen gövdeden signature ve hash alanlarını çıkarıp kalan JSON'un HMAC-SHA256'sını api_secret ile hesaplayın; gelen signature ile eşleşmeli. Alternatif/ek kontrol olarak hash:

hash = SHA256( payment_id + order_id + amount + status + "TRY" + api_secret )     // yatırım
hash = SHA256( withdrawal_id + order_id + amount + status + "TRY" + api_secret )  // çekim
// amount: ondalık sıfırlar atılmış (1250.5, 450)

// PHP — callback doğrulama
$raw  = file_get_contents('php://input');
$data = json_decode($raw, true);
$sig  = $data['signature'] ?? '';
unset($data['signature'], $data['hash']);
$calc = hash_hmac('sha256', json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), $apiSecret);
if (!hash_equals($calc, $sig)) { http_response_code(401); exit('bad signature'); }

if ($data['type'] === 'deposit' && $data['status'] === 'approved') {
    // İdempotent: payment_id daha önce işlendiyse tekrar bakiye ekleme
    creditUser($data['order_id'], (float)$data['approved_amount']);
}
http_response_code(200); echo 'OK';

Durum kodları

Örnek entegrasyon akışı

1. Kullanıcı sitenizde tutar girer → sunucunuz create_payment çağırır (tutar, ad soyad, kendi order_id'niz).
2. Yanıttaki payment_url'e yönlendirin (veya IBAN bilgisini gösterin). payment_id'yi siparişle birlikte saklayın.
3. Müşteri havaleyi yapar; ödeme sayfası otomatik "Onaylandı"ya döner.
4. Callback URL'nize status: approved gelir → imzayı doğrulayın, payment_id daha önce işlenmediyse bakiyeyi approved_amount kadar artırın, 200 dönün.
5. Çekim için create_withdrawal çağırın; sonucu callback veya check_withdrawal ile alın.

# cURL ile hızlı test (signature'ı yukarıdaki yöntemle üretin)
curl -X POST https://mypybnk.com/api/create_payment.php \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"pk_…","amount":100,"customer_name":"Test Kullanıcı","order_id":"T-1","signature":"…"}'

Sık sorulanlar

Müşteri farklı bir isimden gönderirse?

Eşleştirme müşteri adıyla yapılır. Farklı isimden gelen havaleler ödeme ekibi tarafından incelenir; gönderen adı kayıt altına alınır. Müşterilerinizi kendi adlarına kayıtlı hesaptan göndermeleri konusunda uyarın.

Tutar farklı gelirse?

Tolerans dahilindeki farklar approved_amount olarak onaylanır; bakiyeyi bu değere göre işleyin. Büyük farklarda işlem reddedilir veya düzeltilerek onaylanır.

Aynı order_id ile iki kez talep açarsam?

Yatırımda her create_payment yeni bir payment_id üretir. Çekimde withdrawal_id gönderirseniz yinelenen talep oluşmaz.

Test ortamı var mı?

Hesabınız aktif edildiğinde düşük tutarlı gerçek işlemlerle test yapabilirsiniz; API istek ve callback kayıtları panelinizde görünür.