React İle Stripe Entegrasyonu Kullanarak Ödeme Sayfası Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Projeye başlamadan önce geliştirme ortamınızın güncel olduğundan emin olmalısınız. Stripe entegrasyonu, hassas finansal verilerle çalıştığı için güvenlik standartlarına tam uyum gerektirir.

• Node.js (v18 veya üzeri sürüm).
• React (Vite veya Next.js önerilir).
• Stripe hesabı (Test API anahtarları için).
• Stripe CLI (Yerel ortamda webhook testleri için).

Stripe CLI'ı kurmak, ödeme tamamlandığında sunucunuza gelen bildirimleri (webhook) canlıya geçmeden önce test etmenizi sağlar. Terminalinize npm install -g stripe yazarak kurulumu tamamlayabilirsiniz.

Stripe İstemci Kütüphanelerinin Kurulumu

React tarafında Stripe ile güvenli bir şekilde iletişim kurmak için @stripe/stripe-js ve @stripe/react-stripe-js kütüphanelerini kullanacağız. Bu kütüphaneler, kart bilgilerinin doğrudan sizin sunucunuza uğramadan Stripe'a gitmesini sağlar, bu da güvenlik risklerini minimize eder.

npm install @stripe/stripe-js @stripe/react-stripe-js

Bu komut, Stripe'ın JavaScript SDK'sını ve React bileşenlerini projenize ekler. Kurulumdan sonra, Stripe nesnesini uygulamanızın en üst seviyesinde tanımlamanız gerekecektir.

Stripe Provider ile Uygulamayı Sarmalama

Ödeme formunun çalışabilmesi için Stripe'ın "Public Key" (Açık Anahtar) bilgisini tüm alt bileşenlere iletmemiz gerekir. Bunun için Elements sarmalayıcısını kullanırız.

import { loadStripe } from '@stripe/stripe-js';
import { Elements } from '@stripe/react-stripe-js';

const stripePromise = loadStripe('pk_test_sizin_yayinlanabilir_anahtariniz');

function App() {
  return (
    
      
    
  );
}

Burada stripePromise, Stripe SDK'sını asenkron olarak yükler. Elements bileşeni ise, içerisindeki tüm bileşenlere ödeme formunu yönetme yetkisi verir.

Sunucu Tarafında PaymentIntent Oluşturma

Güvenlik gereği, ödeme tutarı ve para birimi gibi bilgiler asla istemci tarafında belirlenmemelidir. Sunucunuzda bir PaymentIntent oluşturarak Stripe'a ödeme niyetinizi bildirmeniz gerekir.

const stripe = require('stripe')('sk_test_sizin_gizli_anahtariniz');

app.post('/create-payment-intent', async (req, res) => {
  const { amount } = req.body;
  const paymentIntent = await stripe.paymentIntents.create({
    amount: amount,
    currency: 'try',
  });
  res.send({ clientSecret: paymentIntent.client_secret });
});

Bu kod, Stripe sunucularında bir işlem oluşturur ve istemciye bir clientSecret döner. Bu anahtar, ödemeyi tamamlamak için React tarafında kullanılacaktır.

React İle Ödeme Formu Bileşeni

Şimdi kullanıcıdan kart bilgilerini alacağımız CheckoutForm bileşenini oluşturalım. Stripe'ın CardElement bileşeni, kart numarası, son kullanma tarihi ve CVC alanlarını otomatik olarak güvenli bir iframe içinde oluşturur.

import { CardElement, useStripe, useElements } from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const stripe = useStripe();
  const elements = useElements();

  const handleSubmit = async (event) => {
    event.preventDefault();
    const { clientSecret } = await fetch('/create-payment-intent', { method: 'POST' }).then(r => r.json());
    
    const result = await stripe.confirmCardPayment(clientSecret, {
      payment_method: { card: elements.getElement(CardElement) }
    });

    if (result.error) console.log(result.error.message);
    else if (result.paymentIntent.status === 'succeeded') alert('Ödeme Başarılı!');
  };

  return (
    
      
      Öde
    
  );
};

Bu bileşen, kullanıcı "Öde" butonuna bastığında Stripe'ın sunucularıyla iletişim kurar ve işlemi doğrular. CardElement kullanımı, kart verilerinin sizin sunucunuza asla ulaşmamasını garantiler.

Ödeme Yöntemlerinin Karşılaştırılması

Kritik Güvenlik Uyarısı: Gizli anahtarlarınızı (Secret Key) asla istemci tarafında (React kodlarında) paylaşmayın. Bu anahtarlar sadece sunucu tarafında (Node.js/Python/PHP) saklanmalıdır. İstemci tarafında yalnızca "Publishable Key" kullanılabilir.

Sıkça Sorulan Sorular

Stripe ile Türkiye'de ödeme alabilir miyim?

Stripe, Türkiye'de doğrudan bir ödeme kuruluşu olarak faaliyet göstermemektedir. Ancak, şirketiniz yurt dışındaysa (örneğin Stripe Atlas ile ABD'de şirket kurduysanız) Stripe'ı Türkiye'den kullanabilirsiniz.

Ödeme başarılı olduğunda sunucuma nasıl haber veririm?

Stripe Webhook'larını kullanmalısınız. Ödeme tamamlandığında Stripe, sunucunuzdaki bir endpoint'e POST isteği gönderir. Bu sayede siparişi veritabanına kaydedebilirsiniz.

CardElement tasarımını değiştirebilir miyim?

Evet, CardElement bileşenine options prop'u üzerinden CSS stilleri geçerek yazı tipi, renk ve boyut gibi özellikleri özelleştirebilirsiniz.

3D Secure zorunlu mu?

Stripe, "SCA" (Strong Customer Authentication) kurallarına uyumludur. Gerekli durumlarda Stripe otomatik olarak 3D Secure doğrulama penceresini açacaktır.

Test kartı numaraları nelerdir?

Stripe'ın dokümantasyonunda belirtilen 4242 4242... ile başlayan test kartı numaralarını kullanarak geliştirme aşamasında gerçek para harcamadan test yapabilirsiniz.

Stripe Entegrasyonunda Hata Ayıklama ve Log Yönetimi

Ödeme süreçlerinde karşılaşılan hatalar genellikle ağ kesintileri, geçersiz kart bilgileri veya yanlış yapılandırılmış API anahtarlarından kaynaklanır. Stripe, her işlem için benzersiz bir payment_intent_id oluşturur. Hata ayıklama sürecinde bu ID'yi Stripe Dashboard üzerinde aratmak, sorunun kaynağını (örneğin; "kart reddedildi" veya "yetersiz bakiye") anında görmenizi sağlar.

React tarafında hata yönetimi için Stripe'ın döndürdüğü error nesnesini kullanmalısınız. Aşağıdaki örnek, kullanıcıya anlamlı hata mesajları göstermek için geliştirilmiş bir yapı sunar:

const handleSubmit = async (event) => {
  event.preventDefault();

  const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
    payment_method: {
      card: elements.getElement(CardElement),
    },
  });

  if (error) {
    // Hata türüne göre kullanıcıyı bilgilendir
    console.error("Ödeme hatası:", error.message);
    setErrorMessage(error.message);
  } else if (paymentIntent.status === 'succeeded') {
    console.log("Ödeme başarıyla tamamlandı!");
  }
};

Performans ve Güvenlik İpuçları

Ödeme sayfalarının yüklenme hızı, dönüşüm oranlarını doğrudan etkiler. Stripe Elements, script dosyalarını Stripe'ın sunucularından güvenli bir şekilde yükler. Bu süreci optimize etmek için şu yöntemleri izleyebilirsiniz:

• Lazy Loading: Ödeme formunu sadece kullanıcı "Öde" butonuna bastığında veya ilgili sekmeye geçtiğinde yükleyerek ana sayfa yüklenme süresini kısaltın.
• Environment Variables: Stripe Publishable Key gibi hassas olmayan ancak uygulama bazlı değişen verileri .env dosyalarında saklayın.
• PCI-DSS Uyumluluğu: Stripe Elements kullandığınızda, kart verileri doğrudan Stripe sunucularına gider. Sunucunuz kart verisine asla dokunmadığı için PCI-DSS kapsamınız "SAQ A" seviyesinde kalır, bu da güvenlik yükünüzü ciddi oranda azaltır.

İleri Seviye: Webhook ile Ödeme Durumunu İzleme

İstemci tarafındaki confirmCardPayment başarılı olsa bile, ağ kopmaları nedeniyle sunucunuz ödemeyi onaylayamayabilir. Bu riski ortadan kaldırmak için Stripe Webhook'larını kullanmak zorunludur. Sunucunuzda kuracağınız bir endpoint üzerinden payment_intent.succeeded olayını dinleyerek veritabanınızı güncel tutabilirsiniz.

// Node.js/Express örneği
app.post('/webhook', express.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    return response.status(400).send(`Webhook Hatası: ${err.message}`);
  }

  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    // Veritabanında siparişi "ödendi" olarak işaretle
    fulfillOrder(paymentIntent);
  }

  response.json({received: true});
});

Bu yapı, ödeme sürecinin hem istemci hem de sunucu tarafında tam bir tutarlılıkla çalışmasını sağlar ve olası veri kayıplarının önüne geçer.

Sonuç

React ile Stripe entegrasyonu, doğru kütüphaneler ve güvenlik pratikleri ile oldukça yönetilebilir bir süreçtir. Bu rehberde, Elements yapısını kurmayı, sunucu tarafında PaymentIntent oluşturmayı ve CardElement ile güvenli bir ödeme formu hazırlamayı öğrendiniz. Bir sonraki adım olarak, Stripe Webhook'larını kullanarak veritabanı işlemlerini otomatize etmeyi ve kullanıcıya ödeme sonrası e-posta gönderimi gibi süreçleri eklemeyi deneyebilirsiniz.

Yasal Uyarı: Bu rehber teknik eğitim amaçlıdır. Finansal verilerin işlenmesi ve saklanması süreçlerinde yerel yasalar ve PCI-DSS uyumluluk kuralları geçerlidir. Ödeme sistemleri kurmadan önce bir hukuk danışmanından destek almanız ve Stripe'ın güncel kullanım sözleşmesini incelemeniz önerilir.