PayTR

Bu rehberde: PayTR mağazanızı mağaza numarası, merchant key ve merchant salt ile bağlarsınız. PayTR'ın Bildirim URL'sine gelen her başarılı ödeme bir iş akışı başlatır: teşekkür mesajı, değerlendirme isteği, WhatsApp takibi.

⏱ 15 dakika

Kimlik kartı#

Ne işe yarar?#

PayTR her ödeme denemesinin sonucunu mağazanın bildirim adresine POST eder. OrqLabs gelen isteğin hash değerini doğrular, PayTR'ye beklediği düz metin OK yanıtını verir ve ödeme başarılıysa akışı şu alanlarla başlatır:

orderId (sizin merchant_oid sipariş numaranız; paymentId de aynı değerdir), status (success), total (tahsil edilen tutar, TL), orderAmount (sipariş tutarı – taksit farkı hariç), currency (TRY, USD, EUR …), paymentType (card / eft), installment, testMode, createdAt, raw.

Başarısız ödemeler (status = failed) de OK ile onaylanır ama akış başlatmaz.

Önemli: PayTR bildirimi alıcının adını, e-postasını veya telefonunu içermez. Mesaj göndermek için orderId (merchant_oid) ile kendi sipariş kaydınızdan müşteri bilgisini alın (ör. HTTP isteği kutusuyla sitenizin sipariş API'sinden veya Google Sheets'ten).

Ön koşullar#

• Onaylı bir PayTR mağazası (iFrame API veya Direkt API entegrasyonu).
• PayTR mağaza panelinde Bilgi sayfasındaki Mağaza No, Mağaza Parola (merchant key) ve Mağaza Gizli Anahtar (merchant salt) değerleri.

Bir mağazanın tek bildirim adresi vardır#

PayTR'de bildirim adresi mağaza başına tektir ve sitenizin sipariş onayı (ödemesi alınan siparişi "ödendi" yapmak) bu adrese bağlıdır. Bu yüzden kuruluma başlamadan önce durumunuzu belirleyin:

Adım adım kurulum#

A) PayTR'de mağaza bilgileri#

1. PayTR mağaza paneline girin.
2. Bilgi sayfasından Mağaza No, Mağaza Parola ve Mağaza Gizli Anahtar değerlerini kopyalayın.

B) OrqLabs'ta bağlama#

1. Entegrasyonlar → PayTR → Bağla → Proje seçin.
2. Mağaza no, Merchant key (mağaza parola) ve Merchant salt (gizli anahtar) alanlarını doldurun → Bağla. Bağlantı testi PayTR'nin durum sorgu servisini rastgele bir sipariş numarasıyla çağırır; "başarılı ödeme bulunamadı" yanıtı bilgilerin doğru olduğunu gösterir.
3. Entegrasyon kartına tıklayın; ayrıntı panelindeki webhook adresini kopyalayın: https://<api-adresi>/api/v1/webhooks/paytr/<entegrasyon-kimliği>.

C) Bildirim URL'si boşsa: OrqLabs adresini girin#

1. PayTR panelinde Destek & Kurulum → Ayarlar → Bildirim URL alanına OrqLabs adresini yapıştırın → Kaydet. Siteniz SSL kullanmıyorsa bile OrqLabs adresi https ile başlar.
2. Test modunda bir ödeme yapın; iş akışının Çalıştırmalar sekmesinde testMode: true olan bir çalıştırma görmelisiniz.

D) Bildirim URL'si sitenizdeyse: isteği iletin (forward)#

Sitenizin PayTR bildirim kodu, kendi işini (hash kontrolü + sipariş onayı) yaptıktan sonra aynı POST verisini değiştirmeden OrqLabs adresine göndermelidir. OrqLabs hash'i aynı merchant key / salt ile kendisi doğrular; alanları silmeyin veya değiştirmeyin. PHP örneği (PayTR'nin bildirim örneğinde echo "OK"; satırından hemen önce):

// PayTR bildirimini OrqLabs'a da ilet (yanıtı beklemeden, kısa zaman aşımıyla)
$ch = curl_init('https://<api-adresi>/api/v1/webhooks/paytr/<entegrasyon-kimliği>');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($_POST));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 5);
curl_exec($ch);
curl_close($ch);
echo "OK";

• PayTR'ye OK'yi siteniz döndürmeye devam etsin; OrqLabs'ın yanıtı yalnızca sizin sitenize gider.
• Gövdeyi JSON olarak iletmeniz de kabul edilir ({"merchant_oid": "…", "status": "…", …}).
• Hazır bir e-ticaret eklentisi kullanıyorsanız ve kodu değiştiremiyorsanız, mağazanızın kendi entegrasyonunu (ör. WooCommerce, Shopify, ikas) dinlemeniz daha kolaydır.

Örnek iş akışları#

1) Ödeme sonrası WhatsApp teşekkürü#

1. Entegrasyon olayı – PAYTR · Payment succeeded.
2. Eğer – {{ $json.testMode }} yanlış (test ödemelerini atlayın).
3. HTTP isteği – sitenizden {{ $json.orderId }} siparişinin müşteri adını ve telefonunu alın.
4. Mesaj gönder – WhatsApp, onaylı sipariş şablonuyla: Merhaba {{ $json.name }}, {{ $node["Entegrasyon olayı"].json.total }} TL'lik ödemeniz alındı. Teşekkür ederiz!

2) Değerlendirme isteği#

Entegrasyon olayı (PAYTR · Payment succeeded) → HTTP isteği (müşteri bilgisi) → Bekle (7 gün) → E-posta gönder (değerlendirme bağlantısı).

İYS ve izin: Ödeme onayı ve teşekkür mesajı işlemsel bildirimdir. Mesaja indirim, kampanya veya yeni ürün tanıtımı eklerseniz ticari elektronik ileti olur; Türkiye'de tüketicilere göndermeden önce alıcının onayı alınmış ve İYS'ye kaydedilmiş olmalıdır (İYS kutusunun Query consent işlemiyle kontrol edebilirsiniz).

Tetikleyici nasıl çalışır?#

• hash = base64(HMAC-SHA256(merchant_oid + merchant_salt + status + total_amount, merchant_key)) sabit zamanlı karşılaştırmayla doğrulanır. Tutmazsa istek 401 ile reddedilir ve OK dönülmez (PayTR yeniden dener).
• Tutarlar PayTR'de 100 ile çarpılmış gelir (34.56 → 3456); OrqLabs bunları TL'ye çevirir.
• PayTR aynı sipariş için birden fazla bildirim gönderebilir; aynı merchant_oid için tekrar gelen bildirimler ikinci kez akış başlatmaz (7 gün).

Limitler#

Kimlik bilgilerini yenileme#

PayTR'de merchant key veya salt değişirse OrqLabs'ta ayrıntı panelinden Kimlik bilgileri → Güncelle ile yenisini girin; aksi hâlde bildirimlerin hash'i tutmaz.

Sık karşılaşılan hatalar#

Sonraki adım#

• iyzico
• Shopier
• Entegrasyonlara genel bakış