Possi Pay Bridge — API Dokümantasyonu

Base URL

HOST https://lisans.possi.com.tr

Kimlik Doğrulama

Her istekte HTTP header olarak API anahtarı gönderin. Anahtarlar proje bazlı verilir.

X-Api-Key: pk_your_project_key

API anahtarı almak için: Possi ile iletişime geçin. Her proje için ayrı anahtar verilir.

POST /api/pay/initiate Ödeme oturumu başlat

Yeni bir ödeme başlatır. PayTR iFrame token ve URL döner. Bu token'ı kendi sayfanızda iFrame içinde gösterin.

İstek Parametreleri

Parametre	Tür	Zorunlu	Açıklama
`oid`	string	✓	Projenizin ürettiği benzersiz sipariş numarası
`tutar`	int	✓	Ödeme tutarı kuruş cinsinden (100 = 1 TL)
`email`	string	✓	Ödeyenin e-posta adresi
`ad`	string		Ödeyenin adı soyadı
`tel`	string		Ödeyenin telefon numarası
`urun`	string		Ürün/hizmet adı (PayTR sepetinde görünür)
`callback_url`	string		Ödeme tamamlandığında POST atılacak URL
`user_ip`	string		Son kullanıcının IP adresi (boş bırakılırsa köprü tespit eder)

İstek Örneği — JSON

POST /api/pay/initiate
X-Api-Key: pk_your_project_key
Content-Type: application/json

{
  "oid":          "BAYI-2026-00421",
  "tutar":        50000,
  "email":        "musteri@example.com",
  "ad":           "Ahmet Yılmaz",
  "tel":          "05321234567",
  "urun":         "QR Menü Lisansı - 1 Yıllık",
  "callback_url": "https://sizin-projeniz.com/odeme/sonuc"
}

İstek Örneği — Form POST

POST /api/pay/initiate
X-Api-Key: pk_your_project_key
Content-Type: application/x-www-form-urlencoded

oid=BAYI-2026-00421&tutar=50000&email=musteri%40example.com
  &ad=Ahmet+Y%C4%B1lmaz&urun=QR+Men%C3%BC+Lisans%C4%B1

Başarılı Yanıt 200 OK

{
  "ok":           true,
  "oid":          "BAYI-2026-00421",
  "iframe_token": "abc123xyz...",
  "iframe_url":   "https://www.paytr.com/odeme/guvenli/abc123xyz..."
}

iFrame Gösterimi

<iframe
  src="https://www.paytr.com/odeme/guvenli/{iframe_token}"
  id="paytriframe"
  frameborder="0"
  scrolling="no"
  style="width:100%;height:560px;border:none;"
></iframe>

<script>
window.addEventListener("message", function(e) {
  if (!e.data || typeof e.data !== "object") return;
  if (e.data.func === "iFrameResize") {
    document.getElementById("paytriframe").style.height = e.data.args[0] + "px";
  }
  if (e.data.func === "iFrameCallback") {
    // args.status: "success" | "fail"
    // args.oid: sipariş numarası
    window.location.href = e.data.args.status === "success"
      ? "/odeme-basarili?oid=" + e.data.args.oid
      : "/odeme-basarisiz";
  }
});
</script>

GET /api/pay/status/{oid} Ödeme durumu sorgula

Verilen sipariş numarasının ödeme durumunu döner.

Başarılı Yanıt 200 OK

{
  "ok":          true,
  "oid":         "BAYI-2026-00421",
  "status":      "Odendi",   // Beklemede | Odendi | Iptal
  "tutar":       50000,
  "urun":        "QR Menü Lisansı - 1 Yıllık",
  "email":       "musteri@example.com",
  "odeme_tarih": "2026-07-31T14:22:00Z",
  "kayit_tarih": "2026-07-31T14:15:00Z"
}

Callback Bildirimi

PayTR ödemeyi onayladıktan sonra köprü, callback_url adresinize aşağıdaki form verisiyle POST atar:

Alan	Değer
`oid`	Sipariş numarası
`status`	`success` veya `fail`
`tutar`	Kuruş cinsinden ödenen tutar

Güvenlik notu: Callback'i doğrulamak için ayrıca GET /api/pay/status/{oid} ile durumu teyit edin. Callback içinde gelen veriyi tek başına güvenilir saymayın.

Hata Yanıtları

HTTP	Kod	Açıklama
401	Unauthorized	X-Api-Key eksik veya geçersiz
400	Bad Request	Zorunlu parametre eksik veya hatalı
404	Not Found	Sipariş bulunamadı (status endpoint)
502	Bad Gateway	PayTR'den token alınamadı

{
  "ok":    false,
  "error": "'oid' zorunludur."
}