API Dokümantasyonu

https://pospaybu.com/api/v1

X-Api-Key: pk_xxx
X-Api-Secret: sk_xxx

curl "https://pospaybu.com/api/v1/payment-services?currency=TRY&amount=1000&installment_count=3" \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx"

// Yanıt:
{ "data": [
  {
    "id": 12,
    "type": "virtual_pos",
    "name": "Garanti TRY",
    "provider": "garanti",
    "bank_code": "0062",
    "mode": "live",                          // live | test
    "currency": "TRY",                       // null = sağlayıcının desteklediği hepsi
    "supported_currencies": ["TRY", "USD"],
    "max_installment": 12,
    "supports_3d": true,
    "checkout_mode": "hosted",               // hosted | direct
    "condition_group": { "id": 3, "name": "Kampanya", "slug": "kampanya" }
  }
] }

# 1) Hosted / iframe — oturumu bu servise SABİTLE
curl -X POST https://pospaybu.com/api/v1/checkout/sessions \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 149.90, "currency": "TRY", "virtual_pos_id": 12 }'

# 2) Direkt API — bu tahsilatı bu servisle al
curl -X POST https://pospaybu.com/api/v1/payments \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 149.90, "virtual_pos_id": 12, "card": { ... } }'

# virtual_pos_id göndermezseniz davranış eskisi gibidir: POS'u
# biz otomatik yönlendiririz.

curl -X POST https://pospaybu.com/api/v1/checkout/sessions \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.90,
    "currency": "TRY",
    "reference": "SIPARIS-1001",
    "callback_url": "https://siteniz.com/odeme/sonuc",
    "customer": { "email": "ahmet@ornek.com", "phone": "5320000000", "code": "CARI-1001" },
    "metadata": { "order_id": 1001 }
  }'
# ── Opsiyonel: ödeme servisini (sanal POS) kendiniz seçin ──────
# Gövdeye şu alanı ekleyin, oturum o servise sabitlenir:
#   "virtual_pos_id": 12
#
# Geçerli id'leri GET /v1/payment-services döner; buradaki 12 yalnızca
# örnektir, kendi hesabınızdaki id'yi kullanın (listede olmayan id → 422).
# Göndermezseniz POS'u biz otomatik yönlendiririz.

HTTP/1.1 201 Created
{
  "token": "Hh3k...long-unguessable-token",
  "reference": "SIPARIS-1001",
  "checkout_url": "https://pospaybu.com/checkout/Hh3k...long-unguessable-token",
  // Oturuma sabitlenen ödeme servisi; null = otomatik POS yönlendirmesi.
  "virtual_pos_id": null,
  // Uygulanan koşul grubu; grup gönderilmediyse ve varsayılan yoksa null.
  "condition_group": { "id": 7, "name": "Kampanya", "slug": "kampanya" }
}

curl -X POST https://pospaybu.com/api/v1/checkout/sessions \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.90,
    "currency": "TRY",
    "reference": "SIPARIS-1001",
    "callback_url": "https://siteniz.com/odeme/sonuc",
    "condition_group_id": 7
  }'
# ── ya da slug ile: ────────────────────────────────────────────
#   "condition_group": "kampanya"
#
# İkisi de opsiyoneldir. Göndermezseniz varsayılan grup (tanımlıysa),
# o da yoksa genel koşullar (tüm taksit/komisyon/POS kuralları) uygulanır.

<!-- Ödeme sayfasını sitenize iframe olarak gömün -->
<iframe
  src="CHECKOUT_URL_BURAYA"
  width="100%" height="720"
  style="border:0; max-width:480px"
  allow="payment">
</iframe>

<!-- ya da tam sayfa yönlendirme: -->
<a href="CHECKOUT_URL_BURAYA">Ödemeye Geç</a>

HTTP/1.1 201 Created
{
  "data": {
    "id": 42,
    "reference": "SIPARIS-1001",
    "method": "card",
    "status": "paid",            // paid | pending(3D) | failed | authorized(provizyon)
    "amount": "149.90",
    "currency": "TRY",
    "installment_count": 1,
    "capture_mode": "auto",
    "net_amount": 149.90,
    "transactions": [
      { "type": "sale", "provider": "garanti", "provider_ref": "...", "status": "success" }
    ]
  }
}

// status === "pending" → 3D Secure gerekiyor.
const meta = res.data.metadata;
if (res.data.status === "pending") {
  if (meta.redirect_html) {
    // Bankaya otomatik POST eden formu müşterinin tarayıcısında render edin:
    document.open(); document.write(meta.redirect_html); document.close();
  } else if (meta.redirect_url) {
    window.location.href = meta.redirect_url;
  }
}
// 3D bitince müşteri BİZİM sonuç ekranımızda kalır (artık sitenize otomatik
// tarayıcı yönlendirmesi YAPILMAZ, #332). Sonucu callback_url'inize gönderdiğimiz
// imzalı server-to-server POST (payment.paid / payment.failed) ile alın.

curl "https://pospaybu.com/api/v1/installments?amount=1000&card_brand=visa" \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx"

// Yanıt:
{ "data": [
  { "installment_count": 1, "card_brand": null,   "commission_rate": "0.00", "total": 1000, "monthly": 1000 },
  { "installment_count": 3, "card_brand": "visa", "commission_rate": "4.50", "total": 1045, "monthly": 348.33 }
] }

curl "https://pospaybu.com/api/v1/payments/SIPARIS-1001" \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx"
// → PaymentResource (status: paid | pending | failed | authorized | refunded)

# Tam iade: body boş. Kısmi iade: "amount" gönderin.
curl -X POST https://pospaybu.com/api/v1/payments/SIPARIS-1001/refund \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50.00 }'

# Provizyon (ön provizyon): tutarı blokede tut, sonra kapat.
curl -X POST https://pospaybu.com/api/v1/payments \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500, "pre_auth": true, "card": { ... } }'
# → data.status = "authorized" (henüz tahsil edilmedi).
# Provizyon kapama / iptal: panel > Ödemeler ekranı
# ("Provizyonu Kapat" / "Provizyonu İptal Et").

# Bakiye sorgu
curl -X POST https://pospaybu.com/api/v1/meal-payments/balance \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "meal_card_id": 1, "card": { "number": "6060...." } }'

# Ödeme (Multinet / Sodexo-Pluxee / Edenred-Ticket / Setcard / Metropol)
curl -X POST https://pospaybu.com/api/v1/meal-payments \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "meal_card_id": 1, "amount": 80, "reference": "SIP-1002",
        "card": { "number": "6060....", "pin": "1234" } }'

POST https://siteniz.com/webhook
X-Pospaybu-Signature: t=1717500000,v1=9f86d08...   (HMAC-SHA256)
X-Pospaybu-Event:     payment.paid
X-Pospaybu-Delivery:  12345                        (tekilleştirme id'si)

{
  "id": 12345,                                  // id + created_at retry'larda SABİT
  "event": "payment.paid",                      //   → aynı teslimatı idempotent ayıklayın
  "created_at": "2026-06-05T10:00:00+00:00",
  "data": {
    "reference": "SIPARIS-1001",
    "status": "paid",
    "amount": 149.90,
    "refunded_amount": 0,
    "currency": "TRY",
    "installment_count": 1,
    "method": "card",
    "paid_at": "2026-06-05T10:00:00+00:00",
    "transaction_id": 84,                        // opsiyonel (son işlem kimliği)
    "metadata": { "order_id": 1001 }
  }
}

"event": "payment.failed",
"data": {
  "reference": "SIPARIS-1001",
  "status": "failed",
  "amount": 149.90,
  ...
  "error_code": "51",
  "error_message": "Yetersiz bakiye"
}

<?php
// İmza doğrulama (PHP) — secret webhook endpoint'i oluştururken bir kez gösterilir.
$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_POSPAYBU_SIGNATURE'] ?? '';
$secret  = 'whsec_xxx';   // endpoint'in kendi secret'i

parse_str(str_replace(',', '&', $header), $p);   // t=..., v1=...
$expected = hash_hmac('sha256', ($p['t'] ?? '') . '.' . $payload, $secret);

if (! hash_equals($expected, $p['v1'] ?? '') || abs(time() - (int)($p['t'] ?? 0)) > 300) {
    http_response_code(400); exit('invalid signature');
}
$event = json_decode($payload, true);
// $event['id'] ile tekilleştirin, sonra 2xx dönün.
http_response_code(200);

POST https://siteniz.com/odeme/sonuc          (checkout callback_url)
X-Pospaybu-Signature: t=1717500000,v1=4b2a9c...
X-Pospaybu-Event:     payment.paid
X-Pospaybu-Delivery:  12346
X-Pospaybu-Key:       pk_xxx     (imza anahtarının türetildiği API anahtarı)

{
  "id": 12346,
  "event": "payment.paid",              // yalnız paid | authorized | failed
  "created_at": "2026-06-05T10:00:00+00:00",
  "data": {
    "reference": "SIPARIS-1001",        // eski GET dönüşündeki reference + status
    "status": "paid",                   //   anahtarları burada da mevcuttur
    "amount": 149.90,
    "refunded_amount": 0,
    "currency": "TRY",
    "installment_count": 1,
    "method": "card",
    "paid_at": "2026-06-05T10:00:00+00:00",
    "metadata": { "order_id": 1001 }
  }
}

signingKey = HMAC_SHA256("pospaybu:callback_url:v1", sha256_hex(sk_...))

<?php
// callback_url imza doğrulama (PHP). Kayıtlı webhook'tan farkı: bu adresin kendine
// ait bir secret'i YOKTUR; imza anahtarını KENDİ API secret'inizden (sk_...) türetin.
$payload = file_get_contents('php://input');
$sig     = $_SERVER['HTTP_X_POSPAYBU_SIGNATURE'] ?? '';
$keyId   = $_SERVER['HTTP_X_POSPAYBU_KEY'] ?? '';   // hangi pk_ kullanıldı

// X-Pospaybu-Key (pk_...) ile eşleşen API anahtarınızın gizli secret'i:
$apiSecret = 'sk_xxx';

// Türev imza anahtarı — backend ile birebir aynı reçete:
$signingKey = hash_hmac('sha256', 'pospaybu:callback_url:v1', hash('sha256', $apiSecret));

parse_str(str_replace(',', '&', $sig), $p);   // t=..., v1=...
$expected = hash_hmac('sha256', ($p['t'] ?? '') . '.' . $payload, $signingKey);

if (! hash_equals($expected, $p['v1'] ?? '') || abs(time() - (int)($p['t'] ?? 0)) > 300) {
    http_response_code(400); exit('invalid signature');
}
// $event['id'] ile tekilleştirin, sonra 2xx dönün (aksi halde tekrar denenir).
http_response_code(200);

HTTP/1.1 422 Unprocessable Content
{ "message": "The amount field is required.",
  "errors": { "amount": ["The amount field is required."] } }