Node.js İle Stripe Entegrasyonu Kullanarak Ödeme Sistemi Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Projeye başlamadan önce sisteminizde Node.js'in güncel bir LTS sürümünün (2026 yılı itibarıyla v22 veya üzeri önerilir) yüklü olduğundan emin olun. Ayrıca bir Stripe hesabı oluşturarak "Dashboard" üzerinden API anahtarlarınızı almanız gerekmektedir.

• Node.js: Sunucu tarafı çalışma ortamı.
• Stripe CLI: Yerel geliştirme ortamında webhook testleri için kritik öneme sahiptir.
• Stripe API Anahtarları: Secret Key ve Publishable Key.
• Express.js: API rotalarını yönetmek için temel web çatısı.

Proje klasörünüzü oluşturun ve gerekli paketleri yükleyerek işe başlayın:

mkdir stripe-odeme-sistemi
cd stripe-odeme-sistemi
npm init -y
npm install express stripe dotenv cors

Bu komutlar, projenizin temel bağımlılıklarını kuracaktır. dotenv paketi, API anahtarlarınızı güvenli bir şekilde saklamak için kullanılacaktır.

Stripe API Yapılandırması ve Güvenlik

API anahtarlarınızı asla doğrudan kod içerisinde paylaşmayın. .env dosyası kullanarak bu verileri ortam değişkenleri olarak saklayın. Stripe ile iletişim kurarken "Secret Key" anahtarınızı sadece sunucu tarafında kullanmalı, "Publishable Key" anahtarını ise frontend tarafında kullanmalısınız.

// .env dosyası içeriği
STRIPE_SECRET_KEY=sk_test_51Q...
STRIPE_PUBLISHABLE_KEY=pk_test_51Q...
PORT=3000

Güvenlik açısından, Stripe Secret Key anahtarınızın asla istemci tarafına (browser) sızmadığından emin olun. Bu anahtar, tüm ödeme işlemlerini yetkilendiren anahtardır.

Payment Intent Oluşturma Adımları

Stripe'da ödeme akışı, bir "Payment Intent" oluşturulmasıyla başlar. Bu, ödeme işleminin durumunu (başarılı, başarısız, bekliyor) takip etmenizi sağlar. Aşağıdaki kod bloğu, sunucu tarafında bir ödeme niyeti oluşturmak için kullanılır.

const express = require('express');
const app = express();
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

app.use(express.json());

app.post('/create-payment-intent', async (req, res) => {
  const { amount, currency } = req.body;

  try {
    const paymentIntent = await stripe.paymentIntents.create({
      amount: amount, // Örn: 1000 (10.00 TL için 1000 kuruş)
      currency: currency,
    });

    res.send({ clientSecret: paymentIntent.client_secret });
  } catch (error) {
    res.status(500).send({ error: error.message });
  }
});

Burada amount değeri en küçük para birimi cinsinden (örneğin kuruş) gönderilmelidir. Bu yöntem, işlemin sunucu tarafında doğrulanmasını garanti altına alır.

Ödeme Yöntemleri Karşılaştırma Tablosu

Webhook Kullanımı ile Ödeme Takibi

Ödeme başarılı olduğunda Stripe'dan gelen bildirimleri (webhook) dinlemeniz gerekir. Bu, veritabanınızı güncellemek veya sipariş onay e-postası göndermek için kritiktir.

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send(`Webhook Hatası: ${err.message}`);
  }

  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    console.log('Ödeme Başarılı:', paymentIntent.id);
  }

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

Webhooklar, uygulamanızın Stripe ile asenkron olarak haberleşmesini sağlar. stripe-signature doğrulaması, gelen isteğin gerçekten Stripe tarafından gönderildiğini kanıtlar.

Kritik Güvenlik Uyarısı: Webhook uç noktanızı her zaman HTTPS üzerinden yayınlayın ve Stripe'ın gönderdiği imza (signature) doğrulaması yapmadan veritabanı işlemlerini gerçekleştirmeyin. Aksi takdirde, sahte ödeme bildirimleri ile sisteminiz manipüle edilebilir.

Hata Yönetimi ve Debug İpuçları

Ödeme sistemlerinde hata yönetimi kullanıcı deneyimi için hayati önem taşır. Stripe API'si, hata durumunda özel hata kodları döndürür. Bu kodları yakalayarak kullanıcıya anlamlı mesajlar gösterebilirsiniz.

// Hata yakalama örneği
try {
  // Ödeme işlemi
} catch (err) {
  switch (err.type) {
    case 'StripeCardError':
      console.log(`Kart hatası: ${err.message}`);
      break;
    default:
      console.log('Beklenmedik bir hata oluştu.');
      break;
  }
}

Geliştirme aşamasında stripe-cli kullanarak stripe listen --forward-to localhost:3000/webhook komutu ile webhook olaylarını yerel sunucunuza yönlendirebilir ve test edebilirsiniz.

Sıkça Sorulan Sorular

Stripe ile ödeme alırken PCI uyumluluğu benim sorumluluğumda mı?

Stripe Elements kullanarak kart bilgilerini doğrudan Stripe sunucularına gönderdiğiniz sürece, kart verileri sizin sunucularınıza hiç uğramaz. Bu durum, PCI uyumluluk sürecinizi ciddi ölçüde basitleştirir.

Ödeme Niyeti (Payment Intent) neden kullanılır?

Payment Intent, ödeme sürecinin yaşam döngüsünü (oluşturma, onaylama, tamamlama) yönetmek için kullanılır. Bu yapı, 3D Secure gibi ek güvenlik adımlarının yönetilmesini kolaylaştırır.

Test kartı bilgilerini nereden bulabilirim?

Stripe'ın resmi dokümantasyonunda yer alan "Test Cards" bölümünde, farklı senaryoları (başarılı ödeme, yetersiz bakiye, kart reddi) denemek için kullanabileceğiniz özel kart numaraları mevcuttur.

Webhook'lar neden gereklidir?

Kullanıcı ödemeyi tamamladıktan sonra tarayıcıyı kapatabilir veya internet bağlantısı kopabilir. Webhooklar, işlemin sonucunun sunucunuza her koşulda ulaşmasını sağlayan garanti mekanizmasıdır.

Abonelik tabanlı ödeme alabilir miyim?

Evet, Stripe "Subscriptions" API'si ile düzenli ödeme alabilirsiniz. Bu rehberdeki Payment Intent yapısı tek seferlik ödemeler içindir, abonelikler için Stripe Billing modülünü incelemelisiniz.

Stripe Entegrasyonunda Performans Optimizasyonu ve Ölçeklenebilirlik

Stripe API'si ile çalışırken, özellikle yüksek trafikli uygulamalarda performans darboğazlarını önlemek için bazı stratejik yaklaşımlar benimsemelisiniz. Node.js'in olay döngüsü (event loop) yapısını korumak ve Stripe ile olan ağ trafiğini optimize etmek, kullanıcı deneyimini doğrudan etkiler.

İsteklerin Asenkron Yönetimi

Ödeme işlemleri sırasında Stripe'a yapılan API çağrılarını bekletmek, ana iş parçacığını bloklamamalıdır. async/await yapısını kullanırken, işlemleri mümkün olduğunca hızlı sonuçlandırmak için Stripe SDK'sının sunduğu idempotency key (eşsizlik anahtarı) özelliğini kullanmanız önerilir. Bu, ağ kesintisi durumunda aynı ödemenin mükerrer olarak çekilmesini engeller.

// Ödeme isteğinde idempotency key kullanımı
const paymentIntent = await stripe.paymentIntents.create({
  amount: 2000,
  currency: 'try',
  payment_method_types: ['card'],
}, {
  idempotencyKey: 'benzersiz_islem_id_12345' 
});

Webhook İşleme Süreçlerinin Ayrıştırılması

Webhook uç noktalarınız (endpoint), Stripe'tan gelen veriyi hızlıca doğrulamalı ve yanıt dönmelidir. Uzun süren veritabanı işlemleri veya e-posta gönderimi gibi süreçleri webhook içinde yürütmek yerine, bir mesaj kuyruğu (Redis, BullMQ veya RabbitMQ) kullanmak sisteminizin yanıt süresini optimize eder.

Stripe Entegrasyonunda İleri Düzey Hata Ayıklama (Debugging)

Geliştirme aşamasında karşılaşılan hataların çoğu, yanlış yapılandırılmış API anahtarları veya geçersiz ödeme verilerinden kaynaklanır. Stripe'ın CLI aracı, yerel ortamda webhook testleri yapmak için en güçlü yardımcıdır.

Stripe CLI ile Yerel Testler

Canlıya çıkmadan önce Stripe CLI kullanarak webhook olaylarını yerel sunucunuza yönlendirebilirsiniz. Bu, gerçek zamanlı hata ayıklama için kritik bir adımdır.

# Stripe CLI ile webhook dinleme
stripe listen --forward-to localhost:3000/webhook

# Belirli bir event'i tetikleme
stripe trigger payment_intent.succeeded

Hata Kodlarını Anlamlandırma

Stripe, hata durumlarında oldukça açıklayıcı nesneler döndürür. Uygulamanızda bu hataları yakalarken, kullanıcıya anlamlı mesajlar dönerken teknik detayları loglamanız önemlidir. Aşağıdaki örnek, yaygın bir kart reddedilme hatasının nasıl yönetileceğini gösterir:

try {
  // Ödeme işlemi
} catch (err) {
  switch (err.type) {
    case 'StripeCardError':
      console.log(`Kart reddedildi: ${err.message}`);
      break;
    case 'StripeRateLimitError':
      console.log('Çok fazla istek, lütfen bekleyin.');
      break;
    default:
      console.log('Beklenmedik bir hata oluştu.');
      break;
  }
}

Bu hata yönetimi yapısı, uygulamanızın dayanıklılığını artırır ve kullanıcıların ödeme sürecinde yaşadığı belirsizlikleri minimize eder. Özellikle StripeRateLimitError durumunda, uygulamanızın bir "exponential backoff" (üstel geri çekilme) stratejisi uygulaması, Stripe API sınırlarına takılmanızı önleyecektir.

Sonuç

Node.js ile Stripe entegrasyonu yapmak, doğru yapılandırıldığında oldukça güvenli ve yönetilebilir bir süreçtir. Bu makalede, bir ödeme niyetinin nasıl oluşturulacağını, webhooklar ile durum takibinin nasıl yapılacağını ve güvenlik önlemlerinin nasıl alınacağını adım adım inceledik. Bir sonraki adım olarak, Stripe'ın sunduğu "Customer" nesnelerini kullanarak kullanıcıların kart bilgilerini güvenli bir şekilde saklamayı ve "Billing" API'sini kullanarak abonelik sistemleri kurmayı deneyebilirsiniz.

Sorumluluk Reddi: Bu makale, yazılım geliştirme süreçlerine dair eğitim amaçlıdır. Ödeme sistemleri, finansal regülasyonlara ve yerel yasalara tabidir. Canlı ortama geçmeden önce Stripe'ın güncel dokümantasyonunu incelemeli ve gerekirse bir hukuk uzmanından veya finansal danışmandan destek almalısınız.