Callback (Webhook) Yapısı

Ödeme tamamlandığında, Paylox sonucu size bildirir. Callback'ler FastAPI üzerinden yönetilir ve merchant'ın belirlediği URL'lere yönlendirilir.

Akış

jetcheckout → Paylox FastAPI → Merchant'ın success_url / fail_url

1. Müşteri ödemeyi tamamlar
2. jetcheckout, Paylox FastAPI'nin callback endpoint'ine bildirim gönderir
3. Paylox, session bilgisini günceller
4. Müşteri, merchant'ın success_url veya fail_url adresine yönlendirilir

Yönlendirme Parametreleri

Başarılı Ödeme

Müşteri şu URL'e yönlendirilir:

https://yoursite.com/payment/success?order_id=ORD-xxx&status=success&session_id=ses_xxx

Parametre	Açıklama
order_id	Sipariş numarası
status	success
session_id	Checkout session ID

Başarısız Ödeme

https://yoursite.com/payment/fail?order_id=ORD-xxx&status=failed&session_id=ses_xxx&message=Yetersiz+bakiye

Parametre	Açıklama
order_id	Sipariş numarası
status	failed
session_id	Checkout session ID
message	Hata mesajı

Doğrulama

Önemli

Callback URL'ine gelen isteğin gerçekten Paylox'tan geldiğini doğrulamak için, session_id ile ödeme durumunu sorgulayın:

GET /api/v1/payment/status/{order_id}?session_id=ses_xxx

Bu sorgu, ödemenin gerçekten tamamlandığını doğrular. Callback parametrelerine güvenmeden önce mutlaka bu kontrolü yapın.

Örnek: Success URL Handler (Node.js Express)

app.get("/payment/success", async (req, res) => {
  const { order_id, session_id } = req.query;

  // Paylox API'den ödeme durumunu doğrula
  const response = await fetch(
    `https://api.paylox.io/api/v1/payment/status/${order_id}?session_id=${session_id}`
  );
  const data = await response.json();

  if (data.success && data.status === "completed") {
    // Siparişi onayla
    await updateOrderStatus(order_id, "paid");
    res.render("payment-success", { order_id });
  } else {
    res.render("payment-error", { message: "Ödeme doğrulanamadı" });
  }
});

Örnek: Success URL Handler (Python Django)

def payment_success(request):
    order_id = request.GET.get("order_id")
    session_id = request.GET.get("session_id")

    # Paylox API'den ödeme durumunu doğrula
    resp = requests.get(
        f"https://api.paylox.io/api/v1/payment/status/{order_id}",
        params={"session_id": session_id}
    )
    data = resp.json()

    if data.get("success") and data.get("status") == "completed":
        Order.objects.filter(ref=order_id).update(status="paid")
        return render(request, "payment_success.html")
    else:
        return render(request, "payment_error.html")