Next.js Türkiye · 9 dakikalık rehber

Next.js Türkiye projesinde ödeme, KVKK ve SEO temelini kurmak

Türkiye'de ürün veya hizmet satan bir Next.js projesinde yalnızca ödeme butonunu çalıştırmak yetmez. Gizli anahtarların sunucuda kalması, ödeme bildiriminin doğrulanması, isteğe bağlı çerezlerin tercihten önce yüklenmemesi ve arama verilerinin gerçek işletme bilgileriyle hazırlanması gerekir.

Bu yazı iyzico, PayTR, çerez tercihleri ve Türkçe SEO için uygulama sırasını gösterir. Hukuki görüş veya sağlayıcı onayı yerine geçmez; canlıya geçmeden önce güncel resmi belgeleri ve kendi iş modelinizi kontrol edin.

1. Ödeme anahtarlarını sunucu sınırında tutun

İmza üretmek için kullanılan API anahtarı, gizli anahtar, merchant salt veya benzeri değerler tarayıcıya gönderilmemelidir. Next.js tarafında bu işlemleri Route Handler ya da yalnızca sunucuda çalışan bir modülde yapın. Gizli değişkeniNEXT_PUBLIC_ önekiyle tanımlamayın ve istemci bileşenine aktarmayın.

Geliştirme, test ve production değerlerini ayrı tutun. Loglarda imza, token, kart verisi veya tam kişisel veri yazmayın. Hata kaydı için sağlayıcının işlem kimliği ve kişisel olmayan dahili sipariş kimliği genellikle daha güvenli bir başlangıçtır.

2. iyzico IYZWSv2 imzasını resmi sırayla üretin

iyzico'nun güncel HMACSHA256 belgesi, yetkilendirme başlığınınIYZWSv2şemasıyla oluşturulmasını ve imzada istek URI'si ile istek gövdesinin kullanılmasını açıklar. İmza dizisinin küçük bir sıralama veya kodlama farkı bile yetkilendirmeyi bozar; kendi tahmininize göre alan eklemeyin.

// Yalnızca sunucuda çalıştırılacak iskelet
const randomKey = createRequestNonce();
const signature = hmacSha256(randomKey + uri + requestBody, secretKey);
const authorization = toIyzwsV2(apiKey, randomKey, signature);

Gerçek formülü, alan biçimlerini ve test değerlerini doğrudan iyzico HMACSHA256 kimlik doğrulama belgesindenalın. Sunucunun gönderdiği gövde ile imzalanan gövdenin bayt düzeyinde aynı olmasını sağlayın; imzadan sonra JSON'ı yeniden biçimlendirmeyin.

3. PayTR'de token isteği ile ödeme bildirimini ayırın

PayTR iFrame akışının ilk adımında token isteği arka planda, sunucudan POST ile yapılır. merchant_oidbenzersiz bir sipariş kimliği olmalı; hash alanları ve sırası resmi örneğe göre hazırlanmalıdır. Dönen iFrame token'ı ödeme formunu göstermek için kullanılır, fakat bu token tek başına siparişin ödendiğini kanıtlamaz.

Ödeme sonucunun kesin kaynağı, PayTR'nin Bildirim URL'nize yaptığı sunucudan sunucuya POST isteğidir. Hash'i zaman sabitli karşılaştırmayla doğrulayın, siparişi merchant_oid üzerinden bulun ve başarı sayfasından gelen tarayıcı oturumuna güvenmeyin.

PayTR aynı işlem için bildirimi birden fazla kez gönderebileceğini belirtiyor. Bu nedenle güncelleme idempotent olmalıdır: zaten tamamlanmış siparişe ikinci kez ürün, kredi veya e-posta teslim etmeyin. Başarılı işleme düz metinOK döndürün; önüne veya arkasına HTML eklemeyin.

• PayTR iFrame API — 1. adım
• PayTR iFrame API — 2. adım ve Bildirim URL

4. İsteğe bağlı çerezleri tercihten önce çalıştırmayın

Bir çerez bandının görünmesi, tek başına tercih yönetimi değildir. Analitik, reklam veya işlevsel amaçla kullanılan isteğe bağlı kodlar kullanıcı seçimi yapılmadan önce yükleniyorsa, arayüzdeki buton gerçek teknik kontrol sağlamaz.

Uygulama katmanında en az şu davranışları ayrı ayrı test edin:

• Zorunlu olmayan scriptler varsayılan durumda çalışmıyor.
• Kabul etme ve reddetme seçenekleri aynı erişilebilirlik düzeyinde.
• Kullanıcı daha sonra tercihlerini açıp değiştirebiliyor.
• Tercih sürümü ve zamanı, gereksiz kişisel veri toplamadan kaydediliyor.
• Metinlerde gerçek kullanılan sağlayıcılar ve amaçlar açıklanıyor.

Kişisel Verileri Koruma Kurumu'nun yayımladığı Çerez Uygulamaları Hakkında Rehberhukuki ve teknik değerlendirme için birincil başlangıç kaynağıdır. Hazır bir metni şirket adı değiştirerek yayımlamak yerine veri akışınızı çıkarın ve metni iş modelinize göre inceletin.

5. Türkçe SEO'da yalnızca doğrulanmış işletme verisini yayımlayın

Sayfa başlığı, açıklama, canonical URL ve sosyal paylaşım görseli temel gereksinimlerdir. Yerel işletme şeması kullanıyorsanız isim, adres, telefon, çalışma saatleri ve hizmet bölgesi gerçek olmalıdır. Örnek şehir veya telefon yer tutucuları production'da JSON-LD olarak yayınlanmamalıdır.

Her sayfa tek bir arama niyetini karşılamalıdır. Örneğin ödeme entegrasyonu sayfası ile iade politikası sayfasını aynı metne sıkıştırmayın. İç bağlantıları kullanıcıya bir sonraki mantıklı adımı gösterecek şekilde kurun; yinelenen, yalnızca anahtar kelime değiştirilmiş sayfalar üretmeyin.

6. Canlıya çıkmadan önce başarısız yolları test edin

Mutlu yolun yanında şu durumları otomatik test kapsamına alın:

• Eksik veya hatalı ödeme ortam değişkenleriyle istek reddediliyor.
• Geçersiz iyzico/PayTR imzası siparişi tamamlamıyor.
• Aynı PayTR bildirimi iki kez geldiğinde teslimat tekrarlanmıyor.
• İsteğe bağlı scriptler red durumunda ağ isteği oluşturmuyor.
• Tercih geri alındığında sonraki sayfa yüklemesinde eski izin kullanılmıyor.
• SEO şemasında yer tutucu kaldığında şema hiç yayımlanmıyor.

Sağlayıcı sandbox ortamı, yerel webhook tüneli ve production alan adı farklı güven sınırlarıdır. Test anahtarını production'da, canlı anahtarı yerel örnek dosyada kullanmayın. Webhook'u yalnızca tarayıcı yönlendirmesiyle test edilmiş saymayın.

Sık sorulan sorular

Tekrarlanan kurulumu kısaltmak

Bu sınırları her projede sıfırdan kurmak istemiyorsanız Türkiye Web Kiti'nin doğrulanmış kapsamınıinceleyin. Paket; Next.js 15 temel proje, çerez tercih kontrolü, iyzico ve PayTR örnek akışları, Türkçe SEO başlangıcı ve düzenlenebilir metin taslakları içerir. Hazır tema, sağlayıcı hesabı veya otomatik hukuki uygunluk vaat etmez.

Satın almadan önce test sayısını, lisansı, dahil olmayan parçaları ve teslimat biçimini ürün sayfasında açıkça görebilirsiniz.

Satın almadan önce teslimat ve mağaza koşullarını okuyabilirsiniz.