PayTR entegrasyonu, Türkiye’deki e-ticaret sitelerinin en güvenli ve hızlı şekilde ödeme almasını sağlayan temel altyapılardan biridir. Geliştiriciler için hazırlanan PayTR Dev dökümantasyonu, sitenize sanal POS entegre ederken ihtiyaç duyacağınız API anahtarları, test ortamı (sandbox) bilgileri ve callback (bildirim) mekanizmasını içerir. Bu rehberde, PayTR API entegrasyonunu sıfırdan sorunsuz bir şekilde nasıl tamamlayacağınızı adım adım bulabilirsiniz.
PayTR API Entegrasyon Adımları
PayTR sistemini web sitenize entegre etmek için öncelikle bir PayTR mağaza hesabına sahip olmanız ve yönetim panelinden API bilgilerini almanız gerekir. Entegrasyon süreci temel olarak dört adımdan oluşur:
1. API Bilgilerinin Alınması
PayTR üye işyeri panelinize giriş yaptıktan sonra “Bilgi” sekmesinden aşağıdaki üç temel parametreyi güvenli bir yere not edin. Bu bilgiler API isteklerinizi imzalamak için kullanılacaktır:
- Mağaza Numarası (Merchant ID): Mağazanıza özel benzersiz sayısal kimlik.
- Mağaza Parolası (Merchant Key): İsteklerin doğrulanmasında kullanılan gizli anahtar.
- Mağaza Gizli Anahtarı (Merchant Salt): Hash (şifreleme) üretimi için kullanılan tuzlama değeri.
2. Token ve Hash Oluşturma
PayTR API’sine gönderilen her isteğin güvenliği, bu üç parametre ve sepet bilgileri kullanılarak oluşturulan SHA256 şifreli bir hash (token) ile sağlanır. PHP, Node.js, C# veya Python dillerinde yazılmış hazır kütüphaneleri kullanarak bu tokenı oluşturabilirsiniz. Gönderilen parametrelerin sırası ve doğruluğu, “Hatalı Hash” hatası almamak için birebir uyuşmalıdır.
3. iFrame Ödeme Formunun Çağrılması
En sık tercih edilen yöntem olan iFrame entegrasyonunda, sunucunuzdan PayTR API’sine bir POST isteği gönderilir. Yanıt olarak dönen “token” değeri ile PayTR’ın güvenli ödeme formu siteniz içerisindeki bir iframe alanında yüklenir. Bu sayede PCI-DSS uyumluluğu zahmetsizce sağlanmış olur.
| Parametre | Tip | Açıklama |
|---|---|---|
| merchant_id | String | PayTR Mağaza Numarası |
| user_ip | String | Ödemeyi yapan kullanıcının IP adresi |
| merchant_oid | String | Sipariş numarası (Benzersiz olmalıdır) |
| payment_amount | Integer | Kuruş cinsinden toplam tutar (Örn: 100 TL için 10000) |
| paytr_token | String | Oluşturulan SHA256 şifreli güvenlik tokenı |
4. Callback (Bildirim) URL Yapılandırması
Ödeme işlemi PayTR tarafında tamamlandığında (başarılı veya başarısız), PayTR sunucuları mağaza panelinizde tanımladığınız Callback URL adresine POST isteği gönderir. Bu istek içerisindeki hash doğrulanmalı, sipariş durumu veritabanınızda güncellenmeli ve ekrana mutlaka “OK” yanıtı yazdırılmalıdır. Aksi takdirde PayTR sunucuları bildirimi tekrar etmeye devam eder.
PayTR Test Ortamı (Sandbox) Kullanımı
Canlı ortama geçmeden önce entegrasyonun doğruluğunu test etmek için PayTR Dev dökümantasyonunda yer alan test kartı bilgilerini kullanabilirsiniz. Test modunda gerçek para çekimi yapılmaz ancak tüm callback ve yönlendirme süreçleri canlı ortamla birebir aynı şekilde simüle edilir.
Sıkça Sorulan Sorular
PayTR entegrasyonunda ‘Hatalı Hash’ hatası neden alınır?
Bu hata genellikle şifreleme (hash) oluşturulurken kullanılan parametrelerin sırasının yanlış olmasından, Türkçe karakter sorunlarından veya Merchant Salt / Merchant Key bilgilerinin karıştırılmasından kaynaklanır. Parametre dizilimini dökümantasyona göre tekrar kontrol edin.
Callback (Bildirim) sayfasına gelen isteklerde neden ‘OK’ dönmeliyiz?
PayTR, ödeme sonucunun sitenize ulaştığından emin olmak ister. Callback sayfanız başarılı işlem sonrası ekrana sadece ‘OK’ (tırnaksız ve büyük harflerle) yazdırmazsa, PayTR sistemi bildirimin başarısız olduğunu varsayar ve belirli aralıklarla bu isteği tekrarlar. Bu durum mükerrer işlem kayıtlarına yol açabilir.
Test kartları ile gerçek işlem arasındaki fark nedir?
Test kartları, API entegrasyonunuzun akışını, sepet verilerinin doğru gidip gitmediğini ve callback mekanizmasının çalışıp çalışmadığını doğrulamak için kullanılır. Test ortamında başarılı dönen işlemler için herhangi bir finansal transfer gerçekleşmez.
